RFC-0030 · Protobuf Schema Adapter
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
This RFC defines the gnomon.io.protobuf module — the Protocol Buffer schema adapter. When a client declaration uses spec: protobuf("./protos/service.proto") or spec: protobuf("buf.build/org/repo"), the compiler invokes this adapter at compile time to parse the .proto source and generate gnomon.io.grpc operations registered on the client.
This RFC is distinct from the gRPC protocol binding (RFC-0026). RFC-0026 defines the runtime binding between gnomon operations and the gRPC wire protocol. This RFC defines how .proto files are parsed to produce those operations. The two modules are designed to work together: gnomon.io.protobuf produces OperationDefinition values; gnomon.io.grpc provides the runtime that executes them.
// Example usage
imports {
gnomon.io.grpc: "^1.0.0"
gnomon.io.protobuf: "^1.0.0"
}
client UserService {
meaning: "Internal user management gRPC service."
spec: protobuf("./protos/user.proto")
baseUrl: "$GRPC_TARGET"
}
After adaptation, UserService.userServiceGetUser, UserService.userServiceListUsers, and so on are available in execute {} blocks and saga steps.
2. Adapter Function Signature
// Exported by gnomon.io.protobuf; called via spec: protobuf(arg)
// source is a file path (relative to the declaring .gnm file) or a Buf registry reference
function protobuf(source: string): SpecImport
The adapter distinguishes between two source forms:
- Local file path — any
sourcevalue that does not begin with a registered registry host. MUST be resolved relative to the directory of the declaring.gnmfile. MAY be a single.protofile or a directory (in which case the adapter MUST discover all.protofiles in the directory tree). - Buf registry reference — a
sourcevalue in the formbuf.build/<org>/<repo>orbuf.build/<org>/<repo>:<version>. The adapter MUST fetch the module from the Buf Schema Registry at compile time and MUST cache the result via the lockfile (§8). If the fetch fails, the adapter MUST emit M30003 (error).
3. Syntax Support
The adapter MUST support the following proto syntaxes:
| Syntax | Support level |
|---|---|
syntax = "proto3" | Full support (primary) |
syntax = "proto2" | Best-effort; deprecated features emit M30001 (warning) |
No syntax declaration | Treated as proto2; emits M30001 |
proto2 deprecated features that are not supported include: required field label (MUST emit M30001; MUST be treated as optional), extensions, and groups. Fields that use unsupported proto2 constructs MUST be typed as JSON with M30001.
proto3 optional fields (optional keyword, proto3_optional descriptor flag) MUST be mapped to optional gnomon fields.
4. Type Mapping
Every protobuf field type MUST be mapped to an gnomon Value type (RFC-0006 §4.A). The adapter MUST apply the following mapping:
| Protobuf type | gnomon type | Notes |
|---|---|---|
string | Text | |
bytes | Binary | |
bool | Boolean | |
int32, sint32, uint32, fixed32, sfixed32 | Integer | |
int64, sint64, uint64, fixed64, sfixed64 | Integer | Truncation warning if values exceed safe integer range is a runtime concern, not a compiler concern |
float, double | Decimal | |
google.protobuf.Timestamp | Timestamp | Well-known type; resolved automatically |
google.protobuf.Duration | Integer | Represented as whole milliseconds; sub-millisecond precision is truncated |
google.protobuf.Empty | void | Used to omit the field from input {} or returns entirely |
google.protobuf.Any | JSON | Emits M30002 (warning) |
google.protobuf.Struct | JSON | Emits M30002 (warning) |
google.protobuf.Value | JSON | Emits M30002 (warning) |
message (named) | TypeDefinition | Registered as <ClientName>.<Namespace>.<MessageName> (§6) |
enum | variant with Text values | Enum value names become the variant arms |
oneof | variant | Each field in the oneof group becomes one arm; arm type is the field type |
repeated T | List<T> | |
map<K, V> | List<{ key: K, value: V }> | Protobuf map keys must be integral or string types; K is mapped accordingly |
4.1 google.protobuf.Duration precision note
google.protobuf.Duration carries nanosecond precision. The adapter MUST convert this to Integer (milliseconds) at the gnomon boundary. Values that have sub-millisecond components MUST be truncated; this is a lossy mapping and the adapter MUST emit a one-time info note when Duration is first encountered in a spec (not per-field; one note per spec).
4.2 Recursive messages
Protobuf messages may be self-referential (e.g., a TreeNode message containing a repeated TreeNode children). The adapter MUST handle this by generating the TypeDefinition with the recursive field typed as List<ClientName.PackageName.TreeNode> and relying on the gnomon type system’s support for recursive types.
5. Service and RPC Mapping
Each service block in a .proto file, combined with each rpc entry within it, MUST produce one gnomon operation.
5.1 Operation naming
The operation name MUST be synthesized from the service name and the RPC name, concatenated in camelCase:
UserService.GetUser→userServiceGetUserPostService.ListPosts→postServiceListPostsHealthService.Check→healthServiceCheck
If a proto package contains only one service, authors may find the service prefix verbose. The adapter MUST NOT suppress it; authors who want shorter names SHOULD declare a hand-authored client with explicit operation names and use the gRPC protocol binding (RFC-0026) directly.
5.2 Streaming mode mapping
| RPC declaration | gnomon mode | Notes |
|---|---|---|
rpc Foo(Request) returns (Response) | unary | Standard request-response |
rpc Foo(Request) returns (stream Response) | server-streaming | Server sends a stream; maps to Stream<T> return type (RFC-0020) |
rpc Foo(stream Request) returns (Response) | client-streaming | Client sends a stream; input typed as Stream<T> |
rpc Foo(stream Request) returns (stream Response) | bidi-streaming | Both directions streamed |
Client-streaming and bidi-streaming operations are unusual in gnomon call sites; they require the caller to produce a Stream<T> value. The adapter MUST generate these operations faithfully. At the call site, the caller supplies a Stream<T> value as the input (for client-streaming) or as both input and return binding (for bidi-streaming); this is achieved by binding a reactive source from RFC-0020 to the operation’s Stream<T> input field in an execute {} block. RFC-0026 governs the wire-level execution of these call modes; there is no separate stream {} block syntax defined by this RFC or RFC-0024. Authors should refer to RFC-0026 §3.3 and §3.4 for the runtime constraints on client-streaming and bidi-streaming input and return types.
5.3 Input and return type mapping
For unary and server-streaming RPCs, the input {} schema MUST be derived from the request message’s fields, and the returns type MUST be the response message type (mapped to a TypeDefinition for non-empty messages, or void for google.protobuf.Empty).
For google.protobuf.Empty request messages, the adapter MUST generate an operation with no input fields (an empty input {}).
6. Namespace Mapping
Proto packages and nested message names MUST be reflected in the gnomon type namespace.
The proto package declaration package foo.bar; with a message Baz MUST produce the gnomon type name <ClientName>.Foo.Bar.Baz. Namespace segments MUST be title-cased. If the .proto file has no package declaration, the message name MUST be registered directly as <ClientName>.Baz.
Enum types MUST follow the same namespacing rules as messages.
Nested messages (messages declared inside another message) MUST be flattened: OuterMessage.InnerMessage in package foo becomes ClientName.Foo.OuterMessage.InnerMessage.
7. Import Resolution
Proto import statements MUST be resolved in two stages:
-
Relative resolution — the adapter MUST resolve the import path relative to the declaring
.protofile’s directory. If the file is found, it MUST be parsed and its types MUST be made available. -
Proto path resolution — if the file is not found relative to the declaring file, the adapter MUST search the directories listed in the
protoPathcompiler option (configured ingnomon.jsonor the project manifest). This is equivalent to the--proto_pathflag inprotoc. The defaultprotoPathMUST include the project root.
Well-known types (google/protobuf/*.proto) MUST be bundled with the adapter and MUST NOT require the caller to supply them.
7.1 Circular imports
If a cycle is detected in the import graph, the adapter MUST emit M30004 (error) and MUST halt. Proto files with circular imports are invalid per the proto specification; this is not a limitation of the adapter.
7.2 Buf registry imports
When source is a Buf registry reference (buf.build/<org>/<repo>), the adapter MUST fetch the compiled FileDescriptorSet from the Buf Schema Registry API at compile time. The fetched bytes MUST be cached in gnomon.lock (§8). On subsequent builds, if the lockfile entry is current, the adapter MUST NOT query the registry.
If the registry fetch fails (network error, authentication failure, module not found), the adapter MUST emit M30003 (error). If a lockfile entry is present from a previous successful fetch, the adapter MUST fall back to the cached FileDescriptorSet and MUST emit M24421 (info, from RFC-0024).
8. Lockfile
The adapter MUST contribute an entry to gnomon.lock (RFC-0024 §6.3). The specHash MUST be computed as the SHA-256 of the concatenation of the SHA-256 hashes of all .proto files in the transitive import closure, sorted lexicographically by their resolved absolute path. Any change to any transitively imported .proto file MUST invalidate the lockfile entry and MUST trigger re-parsing.
For Buf registry sources, the specHash MUST be the SHA-256 of the raw FileDescriptorSet bytes returned by the registry.
{
"clientName": "UserService",
"adapterModule": "gnomon.io.protobuf",
"specHash": "sha256:<hex>",
"specSource": "./protos/user.proto",
"resolvedAt": "2026-01-01T00:00:00Z",
"operationCount": 8
}
9. Diagnostic Codes
This RFC owns the M30xxx diagnostic code range.
| Code | Description | Severity |
|---|---|---|
| M30000 | .proto file not found at declared path | Error |
| M30001 | proto2 deprecated feature used; best-effort support only, field treated as optional | Warning |
| M30002 | Protobuf type cannot be mapped to an gnomon type; field falls back to JSON | Warning |
| M30003 | Buf registry fetch failed (network error or authentication failure) | Error |
| M30004 | Circular import detected in .proto files | Error |
10. Failure Mode Summary
| Code | Description | Severity |
|---|---|---|
| M30000 | .proto file not found | Error |
| M30001 | proto2 deprecated feature (best-effort, JSON fallback for unsupported constructs) | Warning |
| M30002 | Unmappable protobuf type (JSON fallback) | Warning |
| M30003 | Buf registry fetch failed | Error |
| M30004 | Circular import in .proto files | Error |
| M24420 | Spec unreachable, no lockfile entry (from RFC-0024) | Error |
| M24421 | Spec unreachable, using lockfile cache (from RFC-0024) | Info |
| M24422 | Adapter produced zero operations (from RFC-0024) | Warning |
| M24423 | Generated type name conflicts with existing type (from RFC-0024) | Error |