gnomonlearn

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 source value that does not begin with a registered registry host. MUST be resolved relative to the directory of the declaring .gnm file. MAY be a single .proto file or a directory (in which case the adapter MUST discover all .proto files in the directory tree).
  • Buf registry reference — a source value in the form buf.build/<org>/<repo> or buf.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:

SyntaxSupport level
syntax = "proto3"Full support (primary)
syntax = "proto2"Best-effort; deprecated features emit M30001 (warning)
No syntax declarationTreated 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 typegnomon typeNotes
stringText
bytesBinary
boolBoolean
int32, sint32, uint32, fixed32, sfixed32Integer
int64, sint64, uint64, fixed64, sfixed64IntegerTruncation warning if values exceed safe integer range is a runtime concern, not a compiler concern
float, doubleDecimal
google.protobuf.TimestampTimestampWell-known type; resolved automatically
google.protobuf.DurationIntegerRepresented as whole milliseconds; sub-millisecond precision is truncated
google.protobuf.EmptyvoidUsed to omit the field from input {} or returns entirely
google.protobuf.AnyJSONEmits M30002 (warning)
google.protobuf.StructJSONEmits M30002 (warning)
google.protobuf.ValueJSONEmits M30002 (warning)
message (named)TypeDefinitionRegistered as <ClientName>.<Namespace>.<MessageName> (§6)
enumvariant with Text valuesEnum value names become the variant arms
oneofvariantEach field in the oneof group becomes one arm; arm type is the field type
repeated TList<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 → userServiceGetUser
  • PostService.ListPosts → postServiceListPosts
  • HealthService.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 declarationgnomon modeNotes
rpc Foo(Request) returns (Response)unaryStandard request-response
rpc Foo(Request) returns (stream Response)server-streamingServer sends a stream; maps to Stream<T> return type (RFC-0020)
rpc Foo(stream Request) returns (Response)client-streamingClient sends a stream; input typed as Stream<T>
rpc Foo(stream Request) returns (stream Response)bidi-streamingBoth 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:

  1. Relative resolution — the adapter MUST resolve the import path relative to the declaring .proto file’s directory. If the file is found, it MUST be parsed and its types MUST be made available.

  2. Proto path resolution — if the file is not found relative to the declaring file, the adapter MUST search the directories listed in the protoPath compiler option (configured in gnomon.json or the project manifest). This is equivalent to the --proto_path flag in protoc. The default protoPath MUST 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.

CodeDescriptionSeverity
M30000.proto file not found at declared pathError
M30001proto2 deprecated feature used; best-effort support only, field treated as optionalWarning
M30002Protobuf type cannot be mapped to an gnomon type; field falls back to JSONWarning
M30003Buf registry fetch failed (network error or authentication failure)Error
M30004Circular import detected in .proto filesError

10. Failure Mode Summary

CodeDescriptionSeverity
M30000.proto file not foundError
M30001proto2 deprecated feature (best-effort, JSON fallback for unsupported constructs)Warning
M30002Unmappable protobuf type (JSON fallback)Warning
M30003Buf registry fetch failedError
M30004Circular import in .proto filesError
M24420Spec unreachable, no lockfile entry (from RFC-0024)Error
M24421Spec unreachable, using lockfile cache (from RFC-0024)Info
M24422Adapter produced zero operations (from RFC-0024)Warning
M24423Generated type name conflicts with existing type (from RFC-0024)Error