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:
- The
operationprimitive — a named, typed invocation: input schema → output schema, with a declared error taxonomy. - The
clientdeclaration — a named collection of operations, plus metadata about how to reach the external system. - The adapter protocol — a module-level contract that allows
gnomon.io.http,gnomon.io.openapi, and similar modules to extendclientwith 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
| RFC | Role |
|---|---|
| RFC-0001 §4 | Module format and import declarations |
| RFC-0006 §4.B | Declaration kind taxonomy (client is Operations-class) |
| RFC-0008 §6.10 | execute {} block in action — the primary call site |
| RFC-0008 §6.22 | actuator — secondary call site for fire-and-forget |
| RFC-0008 §6.29 | client declaration surface |
| RFC-0008 §6.30 | saga — call site for multi-step compensating processes |
| RFC-0025 | HTTP protocol binding |
| RFC-0026 | gRPC protocol binding |
| RFC-0027 | GraphQL protocol binding |
| RFC-0028 | OpenAPI schema adapter |
| RFC-0029 | tRPC schema adapter |
| RFC-0030 | Protobuf schema adapter |
| RFC-0031 | GraphQL 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, andsagasteps - 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:
| Class | Meaning | Runtime behavior |
|---|---|---|
terminal | Will not resolve on retry; the error is definitive | Fail immediately; propagate to caller or trigger compensation in saga |
transient | May resolve if retried after a delay | Apply the declared retry policy; escalate to terminal if retries exhausted |
ignore | Treat as success | Swallow 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 site | Declaration kind | Semantics |
|---|---|---|
execute {} block | action | Synchronous; result binds into mutations {}; runs before any mutations |
actuator body | actuator | Event-driven; fire-and-forget or result-ignored; no return binding |
saga step | saga | Multi-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:
Clientis a declaredclientin scope (error M24410)operationis declared on the client (or present in its spec) (error M24411)- The
using {}bindings cover allrequiredinput 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
returnsschema (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 successandon failurehandlers (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
errorsselectors at the same specificity overlap (warning) - M24402 —
clientdeclares bothoperations {}andspec:(error; mutually exclusive) - M24403 —
clientdeclaresoperations {}with no operations (warning) - M24404 —
clientauth:uses an unrecognized scheme (error) - M24405 —
clientdeclaresspec:but the referenced adapter function is not in scope (error; checkimports {})
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 arequiredinput 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
returnsschema (error) - M24415 — Unused execute-block binding: result bound in
execute {}is never consumed inmutations {}orafter {}(warning) - M24416 — Actuator call inside
execute {}block; actuator calls are side-effect-only and MUST NOT appear inexecute {}(error) - M24417 — Saga step is missing
on successoron failurehandler; 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
| Code | Description | Severity |
|---|---|---|
| M24401 | Overlapping error selectors at same specificity | Warning |
| M24402 | client declares both operations {} and spec: | Error |
| M24403 | client.operations {} is empty | Warning |
| M24404 | Unrecognized auth: scheme | Error |
| M24405 | spec: adapter function not in scope | Error |
| M24410 | Call site references undeclared client | Error |
| M24411 | Call site references undeclared operation | Error |
| M24412 | using {} missing required field | Error |
| M24413 | using {} binds undeclared field | Error |
| M24414 | Return type conflict | Error |
| M24415 | Unused execute-block binding | Warning |
| M24416 | Actuator call inside execute {} block | Error |
| M24417 | Saga step missing on success or on failure handler | Error |
| M24420 | Spec source unreachable, no lockfile | Error |
| M24421 | Spec source hash changed | Info |
| M24422 | Adapter returned zero operations | Warning |
| M24423 | Adapter-generated type name conflicts with existing type | Error |