gnomonlearn
Docs/RFC-0030/Reference catalog

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.

← Read the authored RFC

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

CodeSeverityDescription
M30000Error.proto file not found at declared path
M30001Warningproto2 deprecated feature used; best-effort support only, field treated as optional
M30002WarningProtobuf type cannot be mapped to an gnomon type; field falls back to JSON
M30003ErrorBuf registry fetch failed (network error or authentication failure)
M30004ErrorCircular 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

  1. Buf registry fetches must be cached in gnomon.lock and not re-queried while the lockfile entry is current. (enforced by: compile-time)
  2. Each (service, rpc) pair in a .proto file must produce exactly one gnomon operation with a camelCase <service><Rpc> name. (enforced by: compile-time)
  3. Every protobuf field type must be mapped to an gnomon Value type, with JSON as the documented fallback. (enforced by: compile-time)
  4. Generated gnomon type names mirror the proto package as title-cased segments under <ClientName>, with nested messages flattened. (enforced by: compile-time)
  5. On detecting a cycle in the proto import graph the adapter must emit M30004 and halt. (enforced by: compile-time)
  6. Proto imports must be resolved first relative to the declaring file and then via the configured protoPath. (enforced by: compile-time)
  7. The adapter must not suppress the service-name prefix on generated operation names. (enforced by: compile-time)
  8. The lockfile specHash must be the SHA-256 over the sorted transitive set of .proto file hashes (or the FileDescriptorSet bytes for registry sources). (enforced by: compile-time)
  9. Well-known types under google/protobuf/*.proto must be bundled with the adapter and never required from the caller. (enforced by: compile-time)
  10. When google.protobuf.Duration is 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

  1. MUST — Buf registry references MUST be fetched at compile time and cached in the lockfile.
  2. MUST — If a Buf registry fetch fails, the adapter MUST emit M30003. (proof citation: rfc0030_b23_grounded; verification pending)
  3. MUST — Local file paths MUST be resolved relative to the declaring .gnm file’s directory.
  4. MUST — When source is a directory, the adapter MUST discover all .proto files in the tree.

Import Resolution

  1. MUST — Buf registry sources MUST fetch the FileDescriptorSet at compile time and cache it in gnomon.lock. (proof citation: rfc0030_b13_grounded; verification pending)
  2. MUST — Circular imports MUST emit M30004 and halt. (proof citation: rfc0030_b15_grounded; verification pending)
  3. MUST — Imports MUST first be resolved relative to the declaring .proto file.
  4. 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)
  5. MUST — The default protoPath MUST include the project root. (proof citation: rfc0030_b34_grounded; verification pending)
  6. MUST — Unresolved imports MUST be searched against the protoPath compiler option.
  7. MUST — Well-known types MUST be bundled with the adapter.
  8. MUST_NOT — When the lockfile entry is current, the adapter MUST NOT query the registry. (proof citation: rfc0030_b41_grounded; verification pending)

Lockfile

  1. MUST — Any change to a transitively imported .proto file MUST invalidate the lockfile entry. (proof citation: rfc0030_b39_grounded; verification pending)
  2. MUST — For Buf registry sources, specHash MUST be SHA-256 of the FileDescriptorSet bytes.
  3. MUST — The adapter MUST contribute an entry to gnomon.lock.
  4. MUST — specHash MUST be SHA-256 of concatenated sorted per-file SHA-256 hashes for local sources.

Namespace Mapping

  1. MUST — Files without a package declaration MUST register messages as ..
  2. MUST — Namespace segments MUST be title-cased.
  3. MUST — Nested messages MUST be flattened into dotted names.
  4. 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

  1. SHOULD — Authors wanting shorter names SHOULD declare a hand-authored client using RFC-0026 directly.
  2. MUST — Each service-rpc pair MUST produce one gnomon operation. (proof citation: rfc0030_b44_grounded; verification pending)
  3. MUST — Input schema MUST be derived from request message fields and returns type from response message type. (proof citation: rfc0030_b6_grounded; verification pending)
  4. MUST — Operation names MUST be synthesized in camelCase from service name and RPC name.
  5. MUST_NOT — The adapter MUST NOT suppress the service prefix in operation names. (proof citation: rfc0030_b47_grounded; verification pending)
  6. MUST — The adapter MUST faithfully generate client-streaming and bidi-streaming operations. (proof citation: rfc0030_b19_grounded; verification pending)
  7. MUST — google.protobuf.Empty request messages MUST produce an empty input {} block. (proof citation: rfc0030_b1_grounded; verification pending)

Syntax Support

  1. MUST — Fields using unsupported proto2 constructs MUST be typed as JSON with M30001. (proof citation: rfc0030_b49_grounded; verification pending)
  2. MUST — The adapter MUST support proto3 fully and proto2 best-effort.
  3. MUST — proto2 ‘required’ fields MUST emit M30001 and be treated as optional. (proof citation: rfc0030_b37_grounded; verification pending)
  4. MUST — proto3 optional fields MUST be mapped to optional gnomon fields. (proof citation: rfc0030_b4_grounded; verification pending)

Type Mapping

  1. MUST — Every protobuf field type MUST be mapped to an gnomon Value type per the mapping table. (proof citation: rfc0030_b21_grounded; verification pending)
  2. MUST — Recursive messages MUST be handled by generating recursive TypeDefinitions.
  3. MUST — The adapter MUST emit a one-time info note per spec when Duration is first encountered.
  4. MUST — google.protobuf.Duration MUST be converted to Integer milliseconds with truncation of sub-millisecond components.

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0006
Depends onRFC-0008
Depends onRFC-0024
Depends onRFC-0026