RFC-0034 server binding contract 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 proposal, 2026-10-03. Owners: I/O runtime, module platform, and the HTTP, gRPC, GraphQL, and tRPC RFC owners. Nothing is deployed, so no live route or payload migration is needed.
Source-bound RDF review
All 44 RFC-0034 domain nodes have source-bound verdicts in
kg/projection-reviews.textproto. Twenty-four match and 20 mismatch:
| Nodes | Source conflict |
|---|---|
declaration/handler-stub, declaration/route-table | §2 and §5 define compiler outputs, not authored named declarations. |
declaration/serve-operation | §2 and §3 define a nested binding block, not a top-level Surface declaration kind. |
Four module/gnomon.io.* nodes | RDF says the protocol modules already register server slots, but RFC-0025/0026/0027/0029 contain only client-side contracts; RFC-0034 §7 labels the server sections “to be authored.” |
Five type/* nodes | They are adapter slot types or conceptual enumerations, not declared Gnomon Value types. HTTPMethod also omits HEAD, which RFC-0025 includes; RFC-0026 calls its gRPC mode CallMode, not GRPCStreamMode. |
| Five required per-operation protocol slots | RDF uses unconditional isRequired true for slots belonging to only one selected protocol. HTTP default mapping may derive method and path without an explicit block. |
field/serve-operation/stream | The RDF summary repeats §7.2’s rule that every streaming mode needs a Stream<T> return. RFC-0026 §3.3 instead requires a stream input and a nonstreaming return for client streaming. |
invariant/binding-modifier-conflict | M34023 is a compile-time conflict in input binding declarations; RDF attaches it to a generated handler stub rather than the binding. |
invariant/serve-stability-gate | RFC-0034 reuses M33008 for stable serve → draft api, while RFC-0033 defines that code for stable api → draft operation. The RDF repeats the conflicting identity. |
The remaining fields, invariants, and serve declaration agree with the
authored RFC at source level. Those verdicts do not establish implementation.
No RDF triples or subject IRIs changed in this review.
Proposed first-release contract
Author and validate the server-side extensions in the four owning protocol
RFCs, then make RFC-0034 cite the exact sections. Give each adapter’s slots
protocol-scoped requiredness, including whether a generated default mapping
counts as satisfying a required slot. Check route collisions across every
compiled serve that can expose the same protocol endpoint, not only inside
one serve, and define normalized route identity for HTTP and each other
protocol.
Align gRPC server streaming with the four-mode table in RFC-0026: unary has
ordinary input and return; server streaming returns Stream<T>; client
streaming has exactly one Stream<T> input and a nonstreaming return; bidi
streaming has a stream input and return. Give the server contract its own
diagnostic for a stable serve referencing a draft api; keep M33008 for the
RFC-0033 stable API condition. Make M34010’s unconditional §4.2/Lean emission
agree with its diagnostic-table --verbose-serve qualifier. For an unsupported
auth scheme, M34021 must reject the build or binding; silently ignoring the
scheme while declaring an error would create an unauthenticated route. Keep
runtime null errors distinct from diagnostics that can actually be emitted by
static stub analysis.
Reclassify generated handler and route artifacts, the nested operation block, and protocol slot schema types. Reclassify the four module nodes only after their owning RFCs actually define the server extensions. Preserve an IRI only where the identity stays the same and record any old-to-new mapping before initial RDF publication.
Acceptance
- Align RFC-0025/0026/0027/0029, RFC-0033/0034, Lean, diagnostics, and RDF; regenerate reference catalogs and Turtle and rebind reviews.
- Compile an API with explicit and default mappings for all four protocols; verify completeness, duplicate routes across APIs, and protocol-scoped slot validation.
- Exercise all gRPC modes, auth-scheme rejection before handler invocation, null-at-boundary behavior, and stable/draft compatibility. Compare checked-in SPARQL results before normative publication.