gnomonlearn
Docs/RFC-0034 server binding contract proposal

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:

NodesSource 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.* nodesRDF 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/* nodesThey 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 slotsRDF 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/streamThe 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-conflictM34023 is a compile-time conflict in input binding declarations; RDF attaches it to a generated handler stub rather than the binding.
invariant/serve-stability-gateRFC-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

  1. Align RFC-0025/0026/0027/0029, RFC-0033/0034, Lean, diagnostics, and RDF; regenerate reference catalogs and Turtle and rebind reviews.
  2. Compile an API with explicit and default mappings for all four protocols; verify completeness, duplicate routes across APIs, and protocol-scoped slot validation.
  3. 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.