gnomonlearn
Docs/RFC-0030 Protobuf adapter contract proposal

RFC-0030 Protobuf adapter 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: proposed first-release reconciliation, 2026-10-03. Owners: spec, compiler, and I/O runtime. No Gnomon deployment exists, but the generated operation ABI, type names, lockfile hash, and RDF IRIs are publication contracts.

Source-bound review

All 40 RFC-0030 domain nodes now have source-bound reviews in kg/projection-reviews.textproto: 26 match and 14 mismatch. The type/Stream mismatch was reviewed earlier in STREAM_CONTRACT_PROPOSAL.md. Thirteen new mismatches are:

NodesConflict
operation/protobufRFC-0030 §2 defines protobuf(source): SpecImport as a compile-time adapter function, but RDF calls it a runtime Operation.
type/Binary, type/voidRFC-0030 maps bytes to Binary, absent from RFC-0006’s complete Value hierarchy. It uses void for absent input/return values, but RDF calls it a Gnomon data type.
type/OperationDefinition, type/SpecImport, type/TypeDefinitionRFC-0024 §6 defines compiler interchange and an opaque import token, not author-writable Value types. The same classification problem appears in RFC-0028.
field/client/baseUrl, field/operation/input, field/operation/returnsThese are shared RFC-0024 slots, but RFC-0030 summaries narrow them to generated gRPC operations. The returns description also depends on unresolved void and Stream<T> contracts.
field/operation/modeRFC-0030 §5.2 and RFC-0026 §3 require four gRPC modes; RFC-0024 §6.1 allows only `“unary”
field/lockfile/specHash, invariant/protobuf-spec-hash-transitiveRFC-0024 §6.3 says file-source specHash hashes source file contents. RFC-0030 §8 hashes a transitive .proto closure and sorts by resolved absolute path, making the hash checkout-location dependent. The RDF field also assigns RFC-0030 ownership to a shared lockfile field.
invariant/protobuf-type-mapping-totalRFC-0030 §4 requires all protobuf fields to map into RFC-0006 Value, but Binary is undefined there and void represents absence rather than a Value.

The remaining 26 nodes agree with the authored rule and Lean summary; those verdicts do not prove runtime behavior. No RDF triples or subject IRIs have changed in this review.

Keep RFC-0024 as owner of client, operation, and lockfile field identities. Define adapter interchange using versioned protobuf messages for any values crossing compiler stages, processes, or files. Give OperationDefinition a four-value call-mode enum matching RFC-0026 and RFC-0030, plus an unspecified value that validation rejects. Keep SpecImport as an opaque compiler token; do not place it in the author-writable Value hierarchy. Model protobuf(source) as an adapter function, distinct from a runtime operation.

Add Binary to the RFC-0006 Value hierarchy with bytes validation and a serialization contract, or choose an existing Value mapping for Protobuf bytes and OpenAPI binary strings. Treat google.protobuf.Empty as an empty input or absent return shape, not a void field type. Resolve Stream<T> against the shared stream proposal before publishing client-streaming or bidi-streaming claims.

Define specHash as a shared lockfile field whose hash algorithm is selected by the adapter and recorded with a versioned algorithm identifier. For local Protobuf sources, hash each file’s bytes in the transitive import closure, sort by normalized logical import path relative to a stable module root, and hash the encoded path-and-digest sequence. Sorting by absolute checkout path is unsuitable: two identical projects at different filesystem paths would produce different lockfile values. For Buf sources, hash the exact pinned FileDescriptorSet bytes. Specify whether an unavailable registry with a valid cached descriptor produces only M24421 or also M30003; an error plus successful fallback is currently ambiguous.

Acceptance before normative release

  1. Owner selects the Binary representation, four-mode adapter ABI, and portable specHash algorithm, including offline Buf diagnostics.
  2. Align RFC-0006, RFC-0024/0026/0028/0030, Lean catalogs, protobuf interchange schemas, diagnostic catalog, and RDF identities. Preserve shared subject IRIs only where they continue to denote the same concept; record any old-to-new IRI mapping for consumers.
  3. Test all four RPC modes through adapter output and gRPC binding, recursive message types, google.protobuf.Empty, binary fields, transitive import changes, identical checkouts at different paths, Buf descriptor pinning, and offline cache behavior. Regenerate generated catalogs and re-review affected source-bound facts. Compare checked-in SPARQL results before a normative RDF release; no live deployment migration is required.