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:
| Nodes | Conflict |
|---|---|
operation/protobuf | RFC-0030 §2 defines protobuf(source): SpecImport as a compile-time adapter function, but RDF calls it a runtime Operation. |
type/Binary, type/void | RFC-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/TypeDefinition | RFC-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/returns | These 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/mode | RFC-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-transitive | RFC-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-total | RFC-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.
Recommended contract
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
- Owner selects the
Binaryrepresentation, four-mode adapter ABI, and portablespecHashalgorithm, including offline Buf diagnostics. - 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.
- 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.