gnomonlearn

RFC-0033 · API Service Declaration

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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Purpose

The existing I/O RFC suite (RFC-0024 through RFC-0031) defines how Gnomon modules act as clients — calling external services over HTTP, gRPC, tRPC, GraphQL, and Protobuf. This covers one direction of the API surface. The symmetric direction — how an Gnomon module exposes its own operations for external callers — has no corresponding model.

This RFC introduces the api declaration: the protocol-agnostic public service surface of an Gnomon module. An api declaration answers the question “what can you call on this module?” without specifying how those calls are transmitted over the wire. Protocol-specific binding rules (route tables, gRPC service names, handler stub generation) are defined in RFC-0034.

The design principle is the same one established by the I/O adapter model: the language owns the protocol-agnostic contract; protocol modules own the wire mapping.


2. Relationship to Existing Concepts

ConceptDirectionContract owner
client (RFC-0024)Outbound — this module calls an external serviceExternal spec or author-declared operations
api (this RFC)Inbound — external callers invoke this moduleThis module
app (RFC-0008 §6.x)UI surface — renders module state in a browser or native appThis module

An api is not a UI surface. It exposes programmatic operations (action, query, procedure) for machine callers. An app renders the same domain model for human callers via a component tree. A module MAY declare both.

The following table illustrates the full client/server symmetry this RFC establishes alongside RFC-0034:

Client sideServer side
client declaration (RFC-0024)api declaration (this RFC)
operation {} slotexposed operation reference in exposes {}
Protocol adapter extends operation {} (RFC-0025–0031)Protocol adapter extends serve-operation {} (RFC-0034)
Compiler generates typed call stubsCompiler generates typed handler stubs

3. Definitions

  • 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.
  • exposed operation: An action, query, or procedure listed in an api declaration’s exposes block.
  • auth scheme: A declared authentication mechanism callers must satisfy to invoke any operation in this api.
  • server binding (RFC-0034): A serve declaration that maps an api’s exposed operations to wire protocol endpoints (HTTP routes, gRPC methods, tRPC procedures, GraphQL operations).
  • handler stub: A compiler-generated typed entry point for a single exposed operation, produced by the server binding (RFC-0034 §7).

4. Invariants

  1. An api MUST reference only action, query, and procedure declarations that are declared in the same module or imported from a declared dependency. Unresolved references MUST produce error M33006.
  2. An api MUST NOT expose mutation, task, actuator, saga, or workflow declarations directly. These are internal execution primitives; they MUST be exposed only through wrapping action or procedure declarations.
  3. An api MUST NOT expose agent or policy declarations. AI participation contracts and policy constraints are internal governance, not public API surface.
  4. An api MUST declare at least one operation in its exposes block. An empty exposes block MUST produce error M33001.
  5. An api’s version field MUST be a valid semantic version string (MAJOR.MINOR.PATCH per SemVer 2.0.0). Malformed version strings MUST produce error M33002.
  6. Auth scheme identifiers in the auth.schemes list MUST be recognized values (§6.3). Unrecognized identifiers MUST produce error M33003.
  7. Error types listed in the errors.common block MUST resolve to declared entity or variant types in scope. Unresolved references MUST produce error M33004.
  8. The scheme none MUST NOT be listed alongside other schemes in the same auth block. Combining none with any other scheme MUST produce error M33005.
  9. A module MAY declare multiple api declarations representing distinct versioned or audience-specific surfaces. The same operation MAY appear in more than one api declaration.
  10. An api MUST NOT expose a declaration marked internal. Attempting to do so MUST produce error M33007.
  11. A stable api MUST NOT expose a draft or experimental operation. Violations MUST produce error M33008.

5. Declaration Syntax

api-decl ::=
  [epistemic-modifier]
  "api" IDENT "{" api-body "}"

epistemic-modifier ::= "draft" | "experimental" | "stable"

api-body ::=
  meaning-slot
  ["version" ":" STRING]
  exposes-block
  [auth-block]
  [errors-block]
  [deprecated-block]

exposes-block ::=
  "exposes" "{" expose-entry* "}"

expose-entry ::=
  expose-kind "[" IDENT ("," IDENT)* "]"

expose-kind ::= "actions" | "queries" | "procedures"

auth-block ::=
  "auth" "{" auth-entry* "}"

auth-entry ::=
  "required" ":" BOOL
| "schemes" "[" auth-scheme ("," auth-scheme)* "]"

auth-scheme ::=
  "bearer-token" | "api-key" | "basic" | "mutual-tls" | "none"

errors-block ::=
  "errors" "{" "common" "[" IDENT ("," IDENT)* "]" "}"

deprecated-block ::=
  "deprecated" "{" "reason" ":" STRING ["since" ":" STRING] "}"

6. Semantics

6.1 exposes Block

The exposes block is the normative roster of operations this api makes callable. Only operations listed here are externally reachable.

  • actions — references to action declarations.
  • queries — references to query declarations.
  • procedures — references to procedure declarations.

All three sub-lists are optional within the block, but at least one entry across all three MUST be present (Invariant 4). Operations NOT listed in exposes are internal to the module. The compiler MUST NOT emit routing metadata or handler stubs for unlisted operations.

6.2 version Field

The version field declares the API version. This value:

  • MAY be used by protocol bindings (RFC-0034) to construct versioned URL paths (e.g., /api/v1/) or Content-Type version headers.
  • Is included in the compiled bundle and is diffable across module versions.
  • MUST be incremented according to RFC-0014 semantic versioning rules when breaking changes are made to any exposed operation’s input or output contract.

If version is omitted, the compiler uses the module version from module.gnm as a default.

6.3 auth Block

The auth block declares authentication requirements for all operations in this api:

  • required: true — every caller MUST authenticate. Unauthenticated requests MUST be rejected by the runtime before any operation handler is invoked. This is the default when auth is omitted.
  • required: false — the API accepts unauthenticated callers. Individual operations MAY still enforce authorization internally via policy declarations.
  • schemes — the set of authentication mechanisms the API will accept. At runtime, a caller using any listed scheme is considered authenticated. Order implies preference (first = most preferred) but does not restrict callers.

Recognized scheme values:

SchemeWire form
bearer-tokenAuthorization: Bearer <token>
api-keyX-Api-Key: <key> header (or ?apiKey=<key> query parameter)
basicAuthorization: Basic <base64>
mutual-tlsClient certificate presented at TLS handshake
noneNo authentication; MUST be declared alone (Invariant 8)

6.4 errors.common Block

The errors.common list declares error types that any operation in this api may return regardless of what the individual operation’s errors {} block declares. These are typically infrastructure-level errors shared across the service surface:

  • NotFound — the requested resource does not exist
  • Unauthorized — the caller is not authenticated or lacks the required scope
  • RateLimitExceeded — the caller has exceeded their rate limit
  • ServiceUnavailable — a transient infrastructure failure

These types MUST be declared entity or variant types in scope. The compiler injects them into the error taxonomy of every exposed operation’s generated handler stub. Operations that already declare a matching error type are not duplicated.

6.5 procedure vs action as Public Surface

An exposed procedure is the preferred entry point for state-changing operations. A procedure wraps an action, enforces the typed input/output contract, and has a bounded error surface. Exposing raw action declarations is permitted but SHOULD be accompanied by a lint warning (M33010) because actions are lower-level execution primitives whose error taxonomy is less constrained.

Exposed query declarations are read-only by definition and are the correct choice for data-retrieval endpoints.


7. Example

// modules/selectsmart/benefits/api.gnm

import "gnomon.errors"

stable api BenefitsAPI {
  meaning: "SelectSmart benefits management API — exposed to employer portals and benefits admin tools."
  version: "1.2.0"

  exposes {
    actions    [enrollInPlan, changeElection, terminateCoverage]
    queries    [getEnrollmentStatus, listAvailablePlans, getHouseholdSummary]
    procedures [submitEnrollment, amendElection]
  }

  auth {
    required: true
    schemes   [bearer-token, api-key]
  }

  errors {
    common [
      gnomon.errors.NotFound,
      gnomon.errors.Unauthorized,
      gnomon.errors.ValidationError,
      gnomon.errors.RateLimitExceeded
    ]
  }
}

draft api BenefitsAdminAPI {
  meaning: "Internal admin surface for plan year management — not exposed to external callers."
  version: "0.1.0"

  exposes {
    actions [archivePlanYear, recalculateEligibility]
    queries [listPlanYears, getPlanYearSummary]
  }

  auth {
    required: true
    schemes  [mutual-tls]
  }
}

8. Declaration Class and File Naming

api is an Operations-class declaration (RFC-0008 §3), alongside action, query, and serve. It MUST be declared in a file named api.gnm within a concept folder. Placing an api declaration in any other file class MUST produce error M08701 (mixed declaration classes).

The api.gnm predefined filename is added to RFC-0001’s predefined file table. The compiler auto-discovers api.gnm under the folder convention; no explicit listing in module.gnm is required.


9. Compiler Validation

  1. Every reference in exposes.actions, exposes.queries, and exposes.procedures MUST resolve to a declared operation of the stated kind in the current module or an imported dependency. Mismatched kinds (e.g., a query referenced under actions) MUST produce error M33006.
  2. An api that exposes an internal declaration MUST produce error M33007.
  3. A stable api that exposes a draft or experimental operation MUST produce error M33008 (supersedes the general M08780 for this context).
  4. The compiler MUST verify that every operation referenced in exposes has no unresolved types in its input {} or returns declaration. An exposed operation with unresolved input or output types MUST produce error M33006 (cannot expose an operation with an incomplete contract).
  5. Two api declarations in the same module with the same version string MUST produce warning M33009.
  6. An api that exposes a raw action (rather than a procedure) MUST produce warning M33010 advising the author to wrap it in a procedure for public surface.

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.

11. Diagnostic Codes (M33xxx)

All diagnostics introduced by this RFC occupy the M33000–M33999 range.

M330x: Declaration structure

  • M33001: api declaration exposes block is empty — at least one operation MUST be listed (error)
  • M33002: api version field is not a valid semantic version string (MAJOR.MINOR.PATCH) (error)
  • M33003: Unrecognized auth scheme identifier in auth.schemes (error)
  • M33004: errors.common entry references an unresolved type — must be a declared entity or variant in scope (error)
  • M33005: none auth scheme combined with other schemes in the same auth block (error)
  • M33006: Operation reference in exposes is unresolved or resolves to the wrong declaration kind (error)
  • M33007: api exposes a declaration marked internal — internal declarations MUST NOT appear in public API surface (error)
  • M33008: stable api exposes a draft or experimental operation (error)
  • M33009: Two api declarations in the same module share the same version string (warning)
  • M33010: api exposes a raw action — prefer wrapping in a procedure for a well-bounded public surface (warning)

M331x: Version and compatibility

  • M33100: api version string is lower than the previously published version for this module (error — cannot publish a lower API version)
  • M33101: Exposed operation input or output contract changed in a way inconsistent with the declared version bump (error — breaking changes require a MAJOR increment per RFC-0014)