RFC-0033 API surface RDF and authentication 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.
Status: source review and first-release contract proposal, 2026-10-03. Owners: I/O runtime, module platform, and spec. No Gnomon deployment exists.
Source-bound RDF review
All 40 RFC-0033 domain nodes have source-bound reviews in
kg/projection-reviews.textproto: 28 match and 12 mismatch. The mismatches
are category errors rather than missing names:
| Nodes | Source conflict |
|---|---|
Five declaration/auth-scheme/* nodes | §5 grammar and §6.3 define recognized auth keywords, not named api declarations. |
Four declaration/error/* nodes | §6.4 uses these as examples of error types that must be declared elsewhere; RFC-0033 does not define them as actual declarations. |
declaration/handler-stub | §3 and RFC-0034 define this as a compiler-generated entry point, not an authored declaration. |
type/AuthScheme, type/SemanticVersion | §5 defines auth scheme grammar alternatives and §6.2 constrains a version string. Neither is declared as an author-writable type in the Gnomon Value hierarchy. |
declaration/serve correctly points to RFC-0034, which owns the server
binding. The API declaration, its two illustrative instances, fields, and
eleven invariants agree with the RFC and Lean at the source level. These
verdicts do not establish compiler or runtime behavior. No RDF triples or
subject IRIs changed during review.
First-release contract questions
RFC-0033 §6.3 defaults auth.required to true when auth is omitted but
defines no default accepted scheme. A binding cannot decide how to authenticate
a caller from that rule alone. The most conservative resolution is for an
omitted auth block to inherit a concrete module or deployment auth policy
only if the owner specifies and validates one; otherwise require an explicit
auth { required: true; schemes [...] } block before publication. An
explicit unauthenticated API must say required: false and should use only
schemes [none]. The spec must define the relation between required: false
and a non-none scheme list (optional authentication, rejected combination,
or another rule), and it must define whether schemes [none] with
required: true is invalid. RFC-0034 bindings must apply the same policy
before invoking a handler.
The BenefitsAdminAPI example says it is an internal admin surface but uses
draft api, whose §3 definition is a public service declaration. The intended
rule appears to be that a draft api can remain unpublished until a serve
binding and release policy expose it. Specify that boundary explicitly;
RFC-0034 already prohibits a stable serve from binding a draft api.
Proposed RDF model and acceptance
Represent auth values as AuthSchemeValue or syntax values, illustrative
error names as examples or references to their actual owning declarations,
and generated handler stubs as compiler artifacts. Represent the SemVer rule
as a constraint on api.version; do not introduce a Gnomon DataType
without a corresponding language declaration. Preserve a subject IRI only
where its identity remains the same, and record any old-to-new IRI mapping
before initial publication.
- Decide the authentication defaults and invalid combinations; align prose, grammar, Lean, diagnostics, RDF, and server bindings.
- Reclassify or remove the 12 mismatched RDF nodes, regenerate Turtle, and rebind source-bound reviews. Compare checked-in SPARQL results.
- Test omitted and explicit auth, all five scheme values,
noneexclusivity, draft versus stable binding, unresolved error types, and handler rejection before a domain operation runs.