gnomonlearn
Docs/RFC-0033/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
api declarationA named, protocol-agnostic declaration that enumerates which of this module’s action, query, and procedure declarations are publicly callable by external systems.
auth schemeA declared authentication mechanism callers must satisfy to invoke any operation in this api.
exposed operationAn action, query, or procedure listed in an api declaration’s exposes block.
handler stubA compiler-generated typed entry point for a single exposed operation, produced by the server binding (RFC-0034 §7).
server bindingA serve declaration (RFC-0034) that maps an api’s exposed operations to wire protocol endpoints (HTTP routes, gRPC methods, tRPC procedures, GraphQL operations).

Diagnostics

CodeSeverityDescription
M33001Errorapi declaration exposes block is empty — at least one operation MUST be listed
M33002Errorapi version field is not a valid semantic version string (MAJOR.MINOR.PATCH)
M33003ErrorUnrecognized auth scheme identifier in auth.schemes
M33004Errorerrors.common entry references an unresolved type — must be a declared entity or variant in scope
M33005Error‘none’ auth scheme combined with other schemes in the same auth block
M33006ErrorOperation reference in exposes is unresolved or resolves to the wrong declaration kind
M33007Errorapi exposes a declaration marked internal — internal declarations MUST NOT appear in public API surface
M33008Errorstable api exposes a draft or experimental operation
M33009WarningTwo api declarations in the same module share the same version string
M33010Warningapi exposes a raw action — prefer wrapping in a procedure for a well-bounded public surface
M33100Errorapi version string is lower than the previously published version for this module
M33101ErrorExposed 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

  1. A stable api MUST NOT expose a draft or experimental operation. (enforced by: compile-time)
  2. An api MUST NOT expose a declaration marked internal. (enforced by: compile-time)
  3. An api MUST NOT expose agent or policy declarations. (enforced by: compile-time)
  4. An api MUST NOT expose mutation, task, actuator, saga, or workflow declarations directly. (enforced by: compile-time)
  5. An api MUST declare at least one operation in its exposes block. (enforced by: compile-time)
  6. 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)
  7. 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)
  8. An api’s version field MUST be a valid SemVer 2.0.0 MAJOR.MINOR.PATCH string. (enforced by: compile-time)
  9. Auth scheme identifiers in auth.schemes MUST be recognized values from the recognized set. (enforced by: compile-time)
  10. Error types listed in errors.common MUST resolve to declared entity or variant types in scope. (enforced by: compile-time)
  11. 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

  1. 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)
  2. 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

  1. MUST — An api declaration MUST be declared in a file named api.gnm within a concept folder. (proof citation: rfc0033_b16_grounded; verification pending)
  2. MUST — Placing an api declaration in any other file class MUST produce error M08701. (proof citation: rfc0033_b10_grounded; verification pending)

Invariants

  1. MUST_NOT — An api MUST NOT directly expose mutation, task, actuator, saga, or workflow declarations. (proof citation: rfc0033_b14_grounded; verification pending)
  2. MUST_NOT — An api MUST NOT expose agent or policy declarations. (proof citation: rfc0033_b6_grounded; verification pending)
  3. MUST — An api MUST declare at least one operation in its exposes block.
  4. 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)
  5. MUST — An api version field MUST be a valid SemVer 2.0.0 MAJOR.MINOR.PATCH string.
  6. MUST — Auth scheme identifiers in auth.schemes MUST be recognized values.
  7. MUST — Error types in errors.common MUST resolve to declared entity or variant types in scope. (proof citation: rfc0033_b18_grounded; verification pending)
  8. MUST_NOT — The auth scheme ‘none’ MUST NOT be combined with other schemes in the same auth block.

Semantics

  1. MUST — At least one entry across actions, queries, or procedures MUST be present in the exposes block.
  2. SHOULD — Exposing raw action declarations SHOULD be accompanied by a lint warning advising authors to wrap them in a procedure.
  3. 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)
  4. 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)
  5. 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

DirectionTarget
Depends onRFC-0001
Depends onRFC-0006
Depends onRFC-0008
Depends onRFC-0024
Extended byRFC-0034