RFC-0033 · 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-0033: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0033.This page is generated from the
lean/Gnomon/Spec/module for RFC-0033. Edit that source and regenerate this catalog.
Title: API Service Declaration
Status: draft
Owners: IO Runtime, Module Platform
Diagnostic range: M33000-M33999
Depends on: RFC-0001, RFC-0006, RFC-0008, RFC-0024
Extended by: RFC-0034
Proof citations in source: 11 / 11. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| api declaration | A named, protocol-agnostic declaration that enumerates which of this module’s action, query, and procedure declarations are publicly callable by external systems. |
| auth scheme | A declared authentication mechanism callers must satisfy to invoke any operation in this api. |
| exposed operation | An action, query, or procedure listed in an api declaration’s exposes block. |
| handler stub | A compiler-generated typed entry point for a single exposed operation, produced by the server binding (RFC-0034 §7). |
| server binding | A serve declaration (RFC-0034) that maps an api’s exposed operations to wire protocol endpoints (HTTP routes, gRPC methods, tRPC procedures, GraphQL operations). |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M33001 | Error | api declaration exposes block is empty — at least one operation MUST be listed |
M33002 | Error | api version field is not a valid semantic version string (MAJOR.MINOR.PATCH) |
M33003 | Error | Unrecognized auth scheme identifier in auth.schemes |
M33004 | Error | errors.common entry references an unresolved type — must be a declared entity or variant in scope |
M33005 | Error | ‘none’ auth scheme combined with other schemes in the same auth block |
M33006 | Error | Operation reference in exposes is unresolved or resolves to the wrong declaration kind |
M33007 | Error | api exposes a declaration marked internal — internal declarations MUST NOT appear in public API surface |
M33008 | Error | stable api exposes a draft or experimental operation |
M33009 | Warning | Two api declarations in the same module share the same version string |
M33010 | Warning | api exposes a raw action — prefer wrapping in a procedure for a well-bounded public surface |
M33100 | Error | api version string is lower than the previously published version for this module |
M33101 | Error | Exposed operation input or output contract changed in a way inconsistent with the declared version bump (breaking changes require a MAJOR increment per RFC-0014) |
Dependency neighborhood
graph LR
nRFC_0033["RFC-0033"]
nRFC_0001["RFC-0001"]
nRFC_0033 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0033 --> nRFC_0006
nRFC_0008["RFC-0008"]
nRFC_0033 --> nRFC_0008
nRFC_0024["RFC-0024"]
nRFC_0033 --> nRFC_0024
nRFC_0034["RFC-0034"]
nRFC_0034 --> nRFC_0033
Invariants
- A stable api MUST NOT expose a draft or experimental operation. (enforced by: compile-time)
- An api MUST NOT expose a declaration marked internal. (enforced by: compile-time)
- An api MUST NOT expose agent or policy declarations. (enforced by: compile-time)
- An api MUST NOT expose mutation, task, actuator, saga, or workflow declarations directly. (enforced by: compile-time)
- An api MUST declare at least one operation in its exposes block. (enforced by: compile-time)
- An api MUST reference only action, query, and procedure declarations declared in the same module or imported from a declared dependency. (enforced by: compile-time)
- An api declaration MUST be placed in a file named api.gnm within a concept folder as an Operations-class declaration. (enforced by: compile-time)
- An api’s version field MUST be a valid SemVer 2.0.0 MAJOR.MINOR.PATCH string. (enforced by: compile-time)
- Auth scheme identifiers in auth.schemes MUST be recognized values from the recognized set. (enforced by: compile-time)
- Error types listed in errors.common MUST resolve to declared entity or variant types in scope. (enforced by: compile-time)
- The scheme none MUST NOT be listed alongside other schemes in the same auth block. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compiler Validation
- MUST — Every reference in exposes.actions, exposes.queries, and exposes.procedures MUST resolve to a declared operation of the stated kind. (proof citation:
rfc0033_b2_grounded; verification pending) - MUST — The compiler MUST verify that every exposed operation has no unresolved types in its input or returns declaration. (proof citation:
rfc0033_b4_grounded; verification pending)
Declaration Class and File Naming
- MUST — An api declaration MUST be declared in a file named api.gnm within a concept folder. (proof citation:
rfc0033_b16_grounded; verification pending) - MUST — Placing an api declaration in any other file class MUST produce error M08701. (proof citation:
rfc0033_b10_grounded; verification pending)
Invariants
- MUST_NOT — An api MUST NOT directly expose mutation, task, actuator, saga, or workflow declarations. (proof citation:
rfc0033_b14_grounded; verification pending) - MUST_NOT — An api MUST NOT expose agent or policy declarations. (proof citation:
rfc0033_b6_grounded; verification pending) - MUST — An api MUST declare at least one operation in its exposes block.
- MUST — An api MUST reference only action, query, and procedure declarations from the same module or imported dependencies. (proof citation:
rfc0033_b21_grounded; verification pending) - MUST — An api version field MUST be a valid SemVer 2.0.0 MAJOR.MINOR.PATCH string.
- MUST — Auth scheme identifiers in auth.schemes MUST be recognized values.
- MUST — Error types in errors.common MUST resolve to declared entity or variant types in scope. (proof citation:
rfc0033_b18_grounded; verification pending) - MUST_NOT — The auth scheme ‘none’ MUST NOT be combined with other schemes in the same auth block.
Semantics
- MUST — At least one entry across actions, queries, or procedures MUST be present in the exposes block.
- SHOULD — Exposing raw action declarations SHOULD be accompanied by a lint warning advising authors to wrap them in a procedure.
- MUST_NOT — The compiler MUST NOT emit routing metadata or handler stubs for operations not listed in exposes. (proof citation:
rfc0033_b25_grounded; verification pending) - MUST — The version field MUST be incremented per RFC-0014 SemVer rules when breaking changes occur to exposed operation contracts. (proof citation:
rfc0033_b0_grounded; verification pending) - MUST — Unauthenticated requests MUST be rejected by the runtime before any operation handler is invoked when auth.required is true. (proof citation:
rfc0033_b12_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0008 |
| Depends on | RFC-0024 |
| Extended by | RFC-0034 |