gnomonlearn
Docs/RFC-0034/Reference catalog

RFC-0034 · 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-0034: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0034.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0034. Edit that source and regenerate this catalog.


Title: Protocol Server Bindings
Status: draft
Owners: IO Runtime, Module Platform
Diagnostic range: M34000-M34999

Depends on: RFC-0001, RFC-0006, RFC-0008, RFC-0024, RFC-0033

Proof citations in source: 17 / 17. Standalone proof verification is pending.


Definitions

TermMeaning
completenessA serve binding is complete when every operation in the referenced api.exposes has a serve-operation block or is covered by the default mapping.
route tableThe compiled set of all protocol-level routes produced by a serve binding, included in the compiled bundle.
serve declarationA named binding that attaches one wire protocol to one api declaration. One serve per protocol per API.
serve-operation blockA per-operation binding block inside a serve declaration, extended by protocol adapter modules with protocol-specific slots.

Diagnostics

CodeSeverityDescription
M34001Errorserve binding is incomplete — one or more operations in api.exposes have no serve-operation block and no applicable default mapping
M34002Errorserve api: references an api declared in another module — cross-module serve bindings are not permitted
M34003Errorserve-operation block names an operation not listed in the referenced api.exposes
M34004ErrorTwo serve-operation blocks in the same serve resolve to the same protocol route
M34005ErrorTwo serve declarations in the same module bind the same api to the same protocol
M34006Errorserve api: reference is unresolved — no api declaration with that name exists in scope
M34007Errorserve protocol: value is unrecognized or the corresponding adapter module is not imported
M34010Infoserve-operation binding derived from protocol default mapping
M34011WarningDefault-mapped operation name does not follow the convention required by the default mapping rule
M34020WarningHandler stub for operation has an unreachable error path — an errors.common type cannot be serialized by this protocol
M34021Errorapi.auth scheme is not supported by the selected protocol adapter
M34022Errorserve-operation declares a streaming mode but the operation’s returns type is not Stream<T>
M34023Errorinput {} field carries a per-field binding modifier AND is referenced by a serve-operation-level slot — conflicting inbound binding
M34024ErrorInbound request contains null for a required field — request rejected at boundary
M34025InfoInbound null for an optional field without a default normalized to field-absent

Dependency neighborhood

graph LR
  nRFC_0034["RFC-0034"]
  nRFC_0001["RFC-0001"]
  nRFC_0034 --> nRFC_0001
  nRFC_0006["RFC-0006"]
  nRFC_0034 --> nRFC_0006
  nRFC_0008["RFC-0008"]
  nRFC_0034 --> nRFC_0008
  nRFC_0024["RFC-0024"]
  nRFC_0034 --> nRFC_0024
  nRFC_0033["RFC-0033"]
  nRFC_0034 --> nRFC_0033

Invariants

  1. A serve declaration MUST reference a resolved api in the same module; cross-module bindings produce M34002. (enforced by: compile-time)
  2. A serve declaration MUST reside in serve.gnm within a concept folder; placement elsewhere produces M08701. (enforced by: compile-time)
  3. A serve-operation block MUST NOT name an operation absent from the referenced api.exposes. (enforced by: compile-time)
  4. A stable serve that references a draft api MUST produce error M33008. (enforced by: compile-time)
  5. An input field carrying a per-field binding modifier MUST NOT also be referenced by a serve-operation-level slot. (enforced by: compile-time)
  6. Every operation in the referenced api.exposes MUST be covered by an explicit serve-operation block or the protocol adapter’s default mapping. (enforced by: compile-time)
  7. Handler stubs MUST NOT emit null in outbound serialization; absent optional fields are omitted from the response. (enforced by: runtime)
  8. Null MUST NOT propagate past the handler stub into the domain operation; nulls are coerced or rejected at the inbound boundary. (enforced by: runtime)
  9. Two serve declarations in the same module MUST NOT bind the same api to the same protocol. (enforced by: compile-time)
  10. Two serve-operation blocks within one serve MUST NOT resolve to the same protocol route. (enforced by: compile-time)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Adapter Protocol

  1. MAY — A protocol adapter MAY declare a default-mapping deriving bindings from operation kind/name
  2. MUST — When default mapping is applied the compiler MUST emit informational diagnostic M34010 (proof citation: rfc0034_b30_grounded; verification pending)

Declaration Class and File Naming

  1. MUST — Placing a serve declaration in any other file class MUST produce error M08701 (proof citation: rfc0034_b22_grounded; verification pending)
  2. MUST — serve MUST be declared in a file named serve.gnm within a concept folder (proof citation: rfc0034_b9_grounded; verification pending)

Handler Stub Generation

  1. MUST — A field with a binding modifier also referenced by a serve-operation-level slot MUST produce error M34023 (proof citation: rfc0034_b16_grounded; verification pending)
  2. MUST — Malformed input MUST be rejected with a protocol-appropriate error before the handler body runs (proof citation: rfc0034_b26_grounded; verification pending)
  3. MUST_NOT — Null MUST NOT propagate past the handler stub into the domain operation (proof citation: rfc0034_b3_grounded; verification pending)
  4. MUST_NOT — Outbound serialization MUST NOT emit null for any field (proof citation: rfc0034_b28_grounded; verification pending)
  5. MUST — Unauthenticated requests MUST be rejected before the handler body runs (proof citation: rfc0034_b24_grounded; verification pending)
  6. MUST — Unauthorized requests MUST be rejected (proof citation: rfc0034_b7_grounded; verification pending)

IO RFC Extensions

  1. MUST — Two HTTP serve-operations resolving to the same method+path MUST produce error M34004 (proof citation: rfc0034_b34_grounded; verification pending)

Multi-Protocol Exposure

  1. MAY — A single api MAY be bound to multiple protocols via multiple serve declarations (proof citation: rfc0034_b32_grounded; verification pending)

The serve Primitive

  1. MUST — A serve-operation block IDENT MUST name an operation listed in api.exposes (proof citation: rfc0034_b0_grounded; verification pending)
  2. MUST_NOT — A serve-operation block MUST NOT produce a route conflicting with another in the same serve
  3. MUST — A stable serve referencing a draft api MUST produce error M33008 (proof citation: rfc0034_b18_grounded; verification pending)
  4. MUST — Every operation in api.exposes MUST be covered by an explicit serve-operation or default mapping (proof citation: rfc0034_b20_grounded; verification pending)
  5. MUST_NOT — Two serve declarations MUST NOT bind the same api to the same protocol in the same module (proof citation: rfc0034_b13_grounded; verification pending)
  6. MUST — api: MUST reference an api declaration in the same module (proof citation: rfc0034_b5_grounded; verification pending)
  7. MUST — protocol: MUST be a recognized value with adapter module imported (proof citation: rfc0034_b11_grounded; verification pending)

Linked References

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