RFC-0030 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0030: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0030.This page is generated from the
lean/Gnomon/Spec/module for RFC-0030. Edit that source and regenerate this catalog.
Title: Protobuf Schema Adapter
Status: draft
Diagnostic range: M30000-M30099
Depends on: RFC-0001, RFC-0006, RFC-0008, RFC-0024, RFC-0026
Proof citations in source: 17 / 17. Standalone proof verification is pending.
Definitions
(none defined)
Diagnostics
| Code | Severity | Description |
|---|---|---|
M30000 | Error | .proto file not found at declared path |
M30001 | Warning | proto2 deprecated feature used; best-effort support only, field treated as optional |
M30002 | Warning | Protobuf type cannot be mapped to an gnomon type; field falls back to JSON |
M30003 | Error | Buf registry fetch failed (network error or authentication failure) |
M30004 | Error | Circular import detected in .proto files |
Dependency neighborhood
graph LR
nRFC_0030["RFC-0030"]
nRFC_0001["RFC-0001"]
nRFC_0030 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0030 --> nRFC_0006
nRFC_0008["RFC-0008"]
nRFC_0030 --> nRFC_0008
nRFC_0024["RFC-0024"]
nRFC_0030 --> nRFC_0024
nRFC_0026["RFC-0026"]
nRFC_0030 --> nRFC_0026
Invariants
- Buf registry fetches must be cached in
gnomon.lockand not re-queried while the lockfile entry is current. (enforced by: compile-time) - Each (service, rpc) pair in a .proto file must produce exactly one gnomon operation with a camelCase
<service><Rpc>name. (enforced by: compile-time) - Every protobuf field type must be mapped to an gnomon Value type, with JSON as the documented fallback. (enforced by: compile-time)
- Generated gnomon type names mirror the proto package as title-cased segments under
<ClientName>, with nested messages flattened. (enforced by: compile-time) - On detecting a cycle in the proto import graph the adapter must emit M30004 and halt. (enforced by: compile-time)
- Proto imports must be resolved first relative to the declaring file and then via the configured
protoPath. (enforced by: compile-time) - The adapter must not suppress the service-name prefix on generated operation names. (enforced by: compile-time)
- The lockfile
specHashmust be the SHA-256 over the sorted transitive set of.protofile hashes (or the FileDescriptorSet bytes for registry sources). (enforced by: compile-time) - Well-known types under
google/protobuf/*.protomust be bundled with the adapter and never required from the caller. (enforced by: compile-time) - When
google.protobuf.Durationis first encountered in a spec the adapter must emit one informational note about sub-millisecond truncation per spec. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Adapter Function Signature
- MUST — Buf registry references MUST be fetched at compile time and cached in the lockfile.
- MUST — If a Buf registry fetch fails, the adapter MUST emit M30003. (proof citation:
rfc0030_b23_grounded; verification pending) - MUST — Local file paths MUST be resolved relative to the declaring .gnm file’s directory.
- MUST — When source is a directory, the adapter MUST discover all .proto files in the tree.
Import Resolution
- MUST — Buf registry sources MUST fetch the FileDescriptorSet at compile time and cache it in gnomon.lock. (proof citation:
rfc0030_b13_grounded; verification pending) - MUST — Circular imports MUST emit M30004 and halt. (proof citation:
rfc0030_b15_grounded; verification pending) - MUST — Imports MUST first be resolved relative to the declaring .proto file.
- MUST — Registry fetch failures with a prior lockfile entry MUST fall back to the cache and emit M24421. (proof citation:
rfc0030_b32_grounded; verification pending) - MUST — The default protoPath MUST include the project root. (proof citation:
rfc0030_b34_grounded; verification pending) - MUST — Unresolved imports MUST be searched against the protoPath compiler option.
- MUST — Well-known types MUST be bundled with the adapter.
- MUST_NOT — When the lockfile entry is current, the adapter MUST NOT query the registry. (proof citation:
rfc0030_b41_grounded; verification pending)
Lockfile
- MUST — Any change to a transitively imported .proto file MUST invalidate the lockfile entry. (proof citation:
rfc0030_b39_grounded; verification pending) - MUST — For Buf registry sources, specHash MUST be SHA-256 of the FileDescriptorSet bytes.
- MUST — The adapter MUST contribute an entry to gnomon.lock.
- MUST — specHash MUST be SHA-256 of concatenated sorted per-file SHA-256 hashes for local sources.
Namespace Mapping
- MUST — Files without a package declaration MUST register messages as
. . - MUST — Namespace segments MUST be title-cased.
- MUST — Nested messages MUST be flattened into dotted names.
- MUST — Proto packages and nested message names MUST be reflected in the gnomon type namespace. (proof citation:
rfc0030_b29_grounded; verification pending)
Service and RPC Mapping
- SHOULD — Authors wanting shorter names SHOULD declare a hand-authored client using RFC-0026 directly.
- MUST — Each service-rpc pair MUST produce one gnomon operation. (proof citation:
rfc0030_b44_grounded; verification pending) - MUST — Input schema MUST be derived from request message fields and returns type from response message type. (proof citation:
rfc0030_b6_grounded; verification pending) - MUST — Operation names MUST be synthesized in camelCase from service name and RPC name.
- MUST_NOT — The adapter MUST NOT suppress the service prefix in operation names. (proof citation:
rfc0030_b47_grounded; verification pending) - MUST — The adapter MUST faithfully generate client-streaming and bidi-streaming operations. (proof citation:
rfc0030_b19_grounded; verification pending) - MUST — google.protobuf.Empty request messages MUST produce an empty input {} block. (proof citation:
rfc0030_b1_grounded; verification pending)
Syntax Support
- MUST — Fields using unsupported proto2 constructs MUST be typed as JSON with M30001. (proof citation:
rfc0030_b49_grounded; verification pending) - MUST — The adapter MUST support proto3 fully and proto2 best-effort.
- MUST — proto2 ‘required’ fields MUST emit M30001 and be treated as optional. (proof citation:
rfc0030_b37_grounded; verification pending) - MUST — proto3 optional fields MUST be mapped to optional gnomon fields. (proof citation:
rfc0030_b4_grounded; verification pending)
Type Mapping
- MUST — Every protobuf field type MUST be mapped to an gnomon Value type per the mapping table. (proof citation:
rfc0030_b21_grounded; verification pending) - MUST — Recursive messages MUST be handled by generating recursive TypeDefinitions.
- MUST — The adapter MUST emit a one-time info note per spec when Duration is first encountered.
- MUST — google.protobuf.Duration MUST be converted to Integer milliseconds with truncation of sub-millisecond components.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0008 |
| Depends on | RFC-0024 |
| Depends on | RFC-0026 |