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.
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
| Term | Meaning |
|---|---|
| completeness | A 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 table | The compiled set of all protocol-level routes produced by a serve binding, included in the compiled bundle. |
| serve declaration | A named binding that attaches one wire protocol to one api declaration. One serve per protocol per API. |
| serve-operation block | A per-operation binding block inside a serve declaration, extended by protocol adapter modules with protocol-specific slots. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M34001 | Error | serve binding is incomplete — one or more operations in api.exposes have no serve-operation block and no applicable default mapping |
M34002 | Error | serve api: references an api declared in another module — cross-module serve bindings are not permitted |
M34003 | Error | serve-operation block names an operation not listed in the referenced api.exposes |
M34004 | Error | Two serve-operation blocks in the same serve resolve to the same protocol route |
M34005 | Error | Two serve declarations in the same module bind the same api to the same protocol |
M34006 | Error | serve api: reference is unresolved — no api declaration with that name exists in scope |
M34007 | Error | serve protocol: value is unrecognized or the corresponding adapter module is not imported |
M34010 | Info | serve-operation binding derived from protocol default mapping |
M34011 | Warning | Default-mapped operation name does not follow the convention required by the default mapping rule |
M34020 | Warning | Handler stub for operation has an unreachable error path — an errors.common type cannot be serialized by this protocol |
M34021 | Error | api.auth scheme is not supported by the selected protocol adapter |
M34022 | Error | serve-operation declares a streaming mode but the operation’s returns type is not Stream<T> |
M34023 | Error | input {} field carries a per-field binding modifier AND is referenced by a serve-operation-level slot — conflicting inbound binding |
M34024 | Error | Inbound request contains null for a required field — request rejected at boundary |
M34025 | Info | Inbound 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
- A serve declaration MUST reference a resolved api in the same module; cross-module bindings produce M34002. (enforced by: compile-time)
- A serve declaration MUST reside in serve.gnm within a concept folder; placement elsewhere produces M08701. (enforced by: compile-time)
- A serve-operation block MUST NOT name an operation absent from the referenced api.exposes. (enforced by: compile-time)
- A stable serve that references a draft api MUST produce error M33008. (enforced by: compile-time)
- An input field carrying a per-field binding modifier MUST NOT also be referenced by a serve-operation-level slot. (enforced by: compile-time)
- 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)
- Handler stubs MUST NOT emit null in outbound serialization; absent optional fields are omitted from the response. (enforced by: runtime)
- Null MUST NOT propagate past the handler stub into the domain operation; nulls are coerced or rejected at the inbound boundary. (enforced by: runtime)
- Two serve declarations in the same module MUST NOT bind the same api to the same protocol. (enforced by: compile-time)
- 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
- MAY — A protocol adapter MAY declare a
default-mappingderiving bindings from operation kind/name - 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
- MUST — Placing a
servedeclaration in any other file class MUST produce error M08701 (proof citation:rfc0034_b22_grounded; verification pending) - MUST —
serveMUST be declared in a file namedserve.gnmwithin a concept folder (proof citation:rfc0034_b9_grounded; verification pending)
Handler Stub Generation
- 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) - MUST — Malformed input MUST be rejected with a protocol-appropriate error before the handler body runs (proof citation:
rfc0034_b26_grounded; verification pending) - MUST_NOT — Null MUST NOT propagate past the handler stub into the domain operation (proof citation:
rfc0034_b3_grounded; verification pending) - MUST_NOT — Outbound serialization MUST NOT emit
nullfor any field (proof citation:rfc0034_b28_grounded; verification pending) - MUST — Unauthenticated requests MUST be rejected before the handler body runs (proof citation:
rfc0034_b24_grounded; verification pending) - MUST — Unauthorized requests MUST be rejected (proof citation:
rfc0034_b7_grounded; verification pending)
IO RFC Extensions
- 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
- MAY — A single
apiMAY be bound to multiple protocols via multipleservedeclarations (proof citation:rfc0034_b32_grounded; verification pending)
The serve Primitive
- MUST — A
serve-operationblock IDENT MUST name an operation listed inapi.exposes(proof citation:rfc0034_b0_grounded; verification pending) - MUST_NOT — A
serve-operationblock MUST NOT produce a route conflicting with another in the sameserve - MUST — A
stableservereferencing adraftapiMUST produce error M33008 (proof citation:rfc0034_b18_grounded; verification pending) - MUST — Every operation in
api.exposesMUST be covered by an explicitserve-operationor default mapping (proof citation:rfc0034_b20_grounded; verification pending) - MUST_NOT — Two
servedeclarations MUST NOT bind the sameapito the sameprotocolin the same module (proof citation:rfc0034_b13_grounded; verification pending) - MUST —
api:MUST reference anapideclaration in the same module (proof citation:rfc0034_b5_grounded; verification pending) - MUST —
protocol:MUST be a recognized value with adapter module imported (proof citation:rfc0034_b11_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0008 |
| Depends on | RFC-0024 |
| Depends on | RFC-0033 |