gnomonlearn

RFC-0024 · I/O Operations Primitive and Adapter Protocol

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

This RFC defines the primitive I/O operation form in gnomon — the irreducible unit of “call something external and get a result back” — and the adapter protocol that allows modules to extend the client declaration with new protocol bindings and schema importers.

The motivation is to avoid embedding protocol-specific knowledge (HTTP methods, gRPC streaming modes, OpenAPI parsing) in the language core. Instead, the language owns:

  1. The operation primitive — a named, typed invocation: input schema → output schema, with a declared error taxonomy.
  2. The client declaration — a named collection of operations, plus metadata about how to reach the external system.
  3. The adapter protocol — a module-level contract that allows gnomon.io.http, gnomon.io.openapi, and similar modules to extend client with protocol-specific slots and schema import functions.

Everything else — HTTP methods, path parameters, proto files, OpenAPI specs — belongs in the protocol and adapter RFCs that extend this one.


2. Linked RFCs

RFCRole
RFC-0001 §4Module format and import declarations
RFC-0006 §4.BDeclaration kind taxonomy (client is Operations-class)
RFC-0008 §6.10execute {} block in action — the primary call site
RFC-0008 §6.22actuator — secondary call site for fire-and-forget
RFC-0008 §6.29client declaration surface
RFC-0008 §6.30saga — call site for multi-step compensating processes
RFC-0025HTTP protocol binding
RFC-0026gRPC protocol binding
RFC-0027GraphQL protocol binding
RFC-0028OpenAPI schema adapter
RFC-0029tRPC schema adapter
RFC-0030Protobuf schema adapter
RFC-0031GraphQL introspection adapter

3. The operation Primitive

An operation is the irreducible unit of external I/O in gnomon. It declares:

  • A name — how the operation is referenced in execute {}, actuator, and saga steps
  • An input schema — a typed record of the values the caller must supply
  • An output schema — a typed record (or scalar, or void) returned on success
  • An error taxonomy — a classification of the ways the operation can fail

An operation has no behavior of its own. It is a declaration of a contract. The runtime resolves the contract to an actual network call via the protocol binding declared in the enclosing client.

operation ::=
  NAME "{" 
    [ "meaning:" STRING ]
    "input" "{" op-field-decl* "}"
    "returns" ":" type | "{" field-decl* "}"
    "errors" "{" error-entry* "}"
    protocol-slots*
  "}"

op-field-decl ::=
  IDENT ":" type-expr { field-modifier } NEWLINE

field-modifier ::=
  "required"
  | "optional"
  | "default" "(" literal ")"
  | "path"
  | "query"
  | "body"
  | "header" [ "(" STRING ")" ]
  | "sensitive"
  | "deprecated"

error-entry ::=
  error-selector ":" error-class

error-selector ::=
  INTEGER          -- specific status/code (e.g. 404, 409)
  | INTEGER "xx"   -- wildcard range (e.g. 5xx, 4xx)
  | "timeout"
  | "network"
  | "*"            -- catch-all; lowest precedence

error-class ::= "terminal" | "transient" | "ignore"

The binding modifiers (path, query, body, header) are protocol-aware. They are defined here at the operation primitive level because they appear on input {} fields, but their semantics are owned by the protocol binding RFC for whichever protocol the enclosing client uses. Protocol bindings that do not support per-field routing MUST ignore unknown binding modifiers and emit a warning.

The field-modifier list is drawn from RFC-0008 §6.3a, which defines the unified field modifier system used across all Gnomon field declarations. op-field-decl is a specialization of field-decl that additionally permits binding modifiers.

Error classes:

ClassMeaningRuntime behavior
terminalWill not resolve on retry; the error is definitiveFail immediately; propagate to caller or trigger compensation in saga
transientMay resolve if retried after a delayApply the declared retry policy; escalate to terminal if retries exhausted
ignoreTreat as successSwallow the error; return a zero/empty value for the output schema

Selectors are matched in specificity order: exact code beats wildcard range beats *. The compiler warns M24401 if two selectors at the same specificity level overlap.


4. The client Declaration

A client is a named collection of operations with shared connection metadata. It is an Operations-class declaration (RFC-0006 §4.B).

client-decl ::=
  "client" NAME "{" 
    [ "meaning:" STRING ]
    connection-slots
    operation-source
  "}"

connection-slots ::=
  ( "baseUrl:" STRING
  | "auth:" auth-scheme
  | "headers" "{" header-entry* "}"
  | "errors" "{" error-entry* "}" )*

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

operation-source ::=
  "operations" "{" operation* "}"     -- hand-authored (protocol-specific slots from binding RFC)
  | spec-import                        -- adapter-generated (see §6)

The errors {} block at the client level declares default error classification applied to all operations in the client. Individual operations may override the default for specific selectors. More-specific operation-level entries win over client-level defaults.

4.1 Hand-authored operations

When operations {} is used, each operation is authored inline. The operation body contains the core primitive slots (input, returns, errors) plus any protocol-specific slots contributed by the protocol binding module in scope (e.g. method, path from gnomon.io.http).

The language core owns only the primitive slots. Protocol-specific slots are syntactic extensions registered by the protocol binding module (§7).

4.2 Adapter-generated operations

When a spec: slot is used instead of operations {}, the operations are generated at compile time by an adapter module. See §6.

A client MUST NOT declare both operations {} and spec: (error M24402).


5. Call Sites

An operation declared in a client may be called from three places:

Call siteDeclaration kindSemantics
execute {} blockactionSynchronous; result binds into mutations {}; runs before any mutations
actuator bodyactuatorEvent-driven; fire-and-forget or result-ignored; no return binding
saga stepsagaMulti-step; result drives per-step on success / on failure handlers

All three call sites use the same binding syntax:

<name> = <Client>.<operation> using { <input bindings> }

The compiler validates at each call site:

  • Client is a declared client in scope (error M24410)
  • operation is declared on the client (or present in its spec) (error M24411)
  • The using {} bindings cover all required input fields (error M24412)
  • No using {} binding names a field not declared in the operation’s input (error M24413)
  • The bound name’s type matches the operation’s declared returns schema (error M24414)

§5.1 Site-Specific Constraints

  • execute {} block: All bindings in the block MUST be consumed (used in mutations {}, after {}, or as input to other bindings). Unused binding → M24415 (warning).
  • actuator: The return value of an actuator call MAY be ignored (fire-and-forget). No M24415 for unused actuator return. Actuator calls MUST NOT appear in execute {} blocks — they are side-effect-only (M24416).
  • saga step: Each step MUST declare both on success and on failure handlers (M24417 if missing).

6. The Adapter Protocol

An adapter is a module that, given a schema source (a file path, a URL, a TypeScript import), produces a set of typed operations in gnomon’s primitive form and registers them on a client declaration.

Adapters are ordinary gnomon modules. They are listed in a project’s imports {} block and bring adapter functions into scope. An adapter function takes one argument — the schema source — and returns an opaque spec-import token that the compiler resolves at compile time.

// In project.gnm
imports {
  gnomon.io.http:    "^1.0.0"
  gnomon.io.openapi: "^1.0.0"
}
// In a client declaration
client WorkOS {
  meaning: "WorkOS user management API."
  spec: openapi("./specs/workos-v2.yaml")
  baseUrl: "https://api.workos.com"
  auth: bearer-token
}

Here, openapi is a function exported by gnomon.io.openapi. It is not a language keyword. The compiler, seeing a spec: slot, asks the module system to resolve the function reference and invoke the adapter at compile time.

6.1 What an adapter must export

An adapter module MUST export:

// OperationDefinition: one callable operation on a client
interface OperationDefinition {
  name: string;                    // operation name as used in execute {} blocks
  protocol: string;                // e.g. "http", "grpc", "graphql"
  inputSchema: Record<string, FieldDef>;  // field name → field definition
  outputSchema: Record<string, FieldDef>; // field name → field definition
  errorCodes: string[];            // protocol-specific error codes this op may emit
  mode?: "unary" | "streaming";   // default: "unary"
}

// TypeDefinition: a named composite type from the external schema
interface TypeDefinition {
  name: string;
  fields: Record<string, FieldDef>;
}

// FieldDef: describes a single field in an operation input or output
interface FieldDef {
  type: string;      // gnomon primitive type name or TypeDefinition name
  required: boolean;
  list: boolean;     // true if field is List<T>
  description?: string;
}

// Normative TypeScript representation of the adapter contract
interface GnomonIoAdapter {
  // Human-readable name for error messages ("OpenAPI 3.x adapter")
  name: string;

  // Called by the compiler with the raw argument from spec: <fn>(arg)
  // Returns the set of operations to register on the client
  resolve(
    arg: string,
    context: AdapterContext,
  ): Promise<AdapterResult>;
}

interface AdapterContext {
  // Absolute path of the declaring .gnm file (for relative path resolution)
  declaringFilePath: string;
  // The project root
  projectRoot: string;
  // The compiler's type registry (for registering generated types)
  typeRegistry: TypeRegistry;
}

interface AdapterResult {
  // The resolved operations, in primitive form
  operations: OperationDefinition[];
  // Any gnomon type definitions generated from the schema (e.g. request/response types)
  types: TypeDefinition[];
  // Lockfile entry: a content hash of the schema source, used for reproducible builds
  schemaHash: string;
}

The compiler invokes the adapter’s resolve() function during the compilation phase, before type checking. The returned operations are inserted into the client’s operation table as if they had been hand-authored. The returned types are registered in the type namespace under <ClientName>.<TypeName>.

6.2 Protocol slot extensions

A protocol binding module (e.g. gnomon.io.http) may register additional syntax slots on the operations {} block. This allows hand-authored HTTP operations to declare method, path, etc., while the language core only knows about input, returns, and errors.

A module registers slot extensions via its module manifest:

// In gnomon.io.http's module.gnm
module gnomon.io.http {
  extends {
    operation {
      method: HTTPMethod required
      path:   Text required
      // ...
    }
  }
}

The compiler loads slot extension manifests from all imported modules before parsing client declarations. This means the parser is aware of protocol-specific slots without the language core hardcoding them.

6.3 Adapter lockfile

Because adapter resolution is network- or filesystem-dependent, the compiler produces a lockfile entry for each spec-backed client. The lockfile records:

  • The adapter function name and module version
  • The schema source argument
  • A content hash of the resolved schema
  • The list of operations generated (names only)

On subsequent builds, if the schema source has not changed (hash matches), the compiler uses the cached operation set without re-invoking the adapter. The lockfile is checked in to source control.

Error M24420 fires if a spec-backed client’s schema source is unreachable and no lockfile entry is present. If a lockfile entry is present but the hash has changed, the compiler re-resolves and updates the lockfile.

The lockfile is a JSON file at <module-dir>/gnomon.lock with the following schema:

{
  "schemaVersion": 1,
  "entries": [
    {
      "clientName": "WorkOS",
      "adapterModule": "gnomon.io.openapi",
      "adapterVersion": "string",
      "specHash": "sha256:<hex>",
      "specSource": "./specs/workos-v2.yaml",
      "resolvedAt": "2026-01-01T00:00:00Z",
      "operationCount": 42
    }
  ]
}

The specHash is SHA-256 of the spec file contents (for file-based specs) or SHA-256 of the canonical introspection response (for network-based specs). The lockfile MUST be committed to version control. The compiler MUST NOT re-query a spec if the lockfile entry’s specHash matches the current spec hash.


7. Compiler Validation

Client-level rules

  • M24401 — Two errors selectors at the same specificity overlap (warning)
  • M24402 — client declares both operations {} and spec: (error; mutually exclusive)
  • M24403 — client declares operations {} with no operations (warning)
  • M24404 — client auth: uses an unrecognized scheme (error)
  • M24405 — client declares spec: but the referenced adapter function is not in scope (error; check imports {})

Operation-level rules

  • M24410 — Call site references undeclared client (error)
  • M24411 — Call site references operation not declared on the client or present in its spec (error)
  • M24412 — using {} does not supply a required input field (error)
  • M24413 — using {} binds a field not declared in the operation input (error)
  • M24414 — Bound result name’s inferred type conflicts with the operation’s returns schema (error)
  • M24415 — Unused execute-block binding: result bound in execute {} is never consumed in mutations {} or after {} (warning)
  • M24416 — Actuator call inside execute {} block; actuator calls are side-effect-only and MUST NOT appear in execute {} (error)
  • M24417 — Saga step is missing on success or on failure handler; both are required (error)

Adapter rules

  • M24420 — Spec source unreachable and no lockfile entry present (error)
  • M24421 — Spec source hash changed since last lock; lockfile updated (info)
  • M24422 — Adapter returned zero operations (warning)
  • M24423 — Adapter returned a type name that conflicts with an existing type in scope (error)

8. What This RFC Does NOT Define

The following are explicitly delegated to the extending RFCs:

  • HTTP-specific operation slots (method, path, headers, body encoding) → RFC-0025
  • gRPC-specific operation slots (service, rpc, streaming mode) → RFC-0026
  • GraphQL-specific operation slots (query/mutation/subscription, selection set) → RFC-0027
  • OpenAPI 3.x parsing and operation generation → RFC-0028
  • tRPC router type extraction → RFC-0029
  • Protocol Buffer parsing → RFC-0030
  • GraphQL schema introspection → RFC-0031

9. Failure Mode Summary

CodeDescriptionSeverity
M24401Overlapping error selectors at same specificityWarning
M24402client declares both operations {} and spec:Error
M24403client.operations {} is emptyWarning
M24404Unrecognized auth: schemeError
M24405spec: adapter function not in scopeError
M24410Call site references undeclared clientError
M24411Call site references undeclared operationError
M24412using {} missing required fieldError
M24413using {} binds undeclared fieldError
M24414Return type conflictError
M24415Unused execute-block bindingWarning
M24416Actuator call inside execute {} blockError
M24417Saga step missing on success or on failure handlerError
M24420Spec source unreachable, no lockfileError
M24421Spec source hash changedInfo
M24422Adapter returned zero operationsWarning
M24423Adapter-generated type name conflicts with existing typeError