RFC-0024 · 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-0024: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0024.This page is generated from the
lean/Gnomon/Spec/module for RFC-0024. Edit that source and regenerate this catalog.
Title: I/O Operations Primitive and Adapter Protocol
Status: draft
Owners: IO Runtime, Module Platform
Diagnostic range: M24400-M24499
Depends on: RFC-0001, RFC-0006, RFC-0008
Extended by: RFC-0025, RFC-0026, RFC-0027, RFC-0028, RFC-0029, RFC-0030, RFC-0031
Proof citations in source: 4 / 4. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| adapter | A module that, given a schema source, produces a set of typed operations in gnomon’s primitive form and registers them on a client declaration. |
| client | A named collection of operations with shared connection metadata; an Operations-class declaration. |
| ignore error | An error class meaning the failure is treated as success; the runtime swallows the error and returns a zero/empty value for the output schema. |
| operation | The irreducible unit of external I/O in gnomon: a named, typed invocation declaring an input schema, output schema, and error taxonomy. Has no behavior of its own; is a contract resolved at runtime via the enclosing client’s protocol binding. |
| terminal error | An error class meaning the failure will not resolve on retry; runtime fails immediately and propagates to caller or triggers compensation in saga. |
| transient error | An error class meaning the failure may resolve if retried after a delay; runtime applies the declared retry policy and escalates to terminal if exhausted. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M24401 | Warning | Two errors selectors at the same specificity overlap |
M24402 | Error | client declares both operations {} and spec: (mutually exclusive) |
M24403 | Warning | client declares operations {} with no operations |
M24404 | Error | client auth: uses an unrecognized scheme |
M24405 | Error | client declares spec: but the referenced adapter function is not in scope |
M24410 | Error | Call site references undeclared client |
M24411 | Error | Call site references operation not declared on the client or present in its spec |
M24412 | Error | using {} does not supply a required input field |
M24413 | Error | using {} binds a field not declared in the operation input |
M24414 | Error | Bound result name’s inferred type conflicts with the operation’s returns schema |
M24415 | Warning | Unused execute-block binding: result bound in execute {} is never consumed in mutations {} or after {} |
M24416 | Error | Actuator call inside execute {} block; actuator calls are side-effect-only and MUST NOT appear in execute {} |
M24417 | Error | Saga step is missing on success or on failure handler; both are required |
M24420 | Error | Spec source unreachable and no lockfile entry present |
M24421 | Info | Spec source hash changed since last lock; lockfile updated |
M24422 | Warning | Adapter returned zero operations |
M24423 | Error | Adapter returned a type name that conflicts with an existing type in scope |
Dependency neighborhood
graph LR
nRFC_0024["RFC-0024"]
nRFC_0001["RFC-0001"]
nRFC_0024 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0024 --> nRFC_0006
nRFC_0008["RFC-0008"]
nRFC_0024 --> nRFC_0008
nRFC_0025["RFC-0025"]
nRFC_0025 --> nRFC_0024
nRFC_0026["RFC-0026"]
nRFC_0026 --> nRFC_0024
nRFC_0027["RFC-0027"]
nRFC_0027 --> nRFC_0024
nRFC_0028["RFC-0028"]
nRFC_0028 --> nRFC_0024
nRFC_0029["RFC-0029"]
nRFC_0029 --> nRFC_0024
nRFC_0030["RFC-0030"]
nRFC_0030 --> nRFC_0024
nRFC_0031["RFC-0031"]
nRFC_0031 --> nRFC_0024
Invariants
- A client MUST NOT declare both operations {} and spec:; the two operation sources are mutually exclusive. (enforced by: compile-time)
- Actuator calls are side-effect-only and MUST NOT appear inside an action’s execute {} block. (enforced by: compile-time)
- All bindings produced in an execute {} block MUST be consumed in mutations {}, after {}, or as inputs to other bindings. (enforced by: compile-time)
- An operation has no behavior of its own; it is purely a contract resolved by the enclosing client’s protocol binding. (enforced by: compile-time)
- Each saga step MUST declare both an on success and an on failure handler. (enforced by: compile-time)
- Error selectors are matched in specificity order: exact code beats wildcard range beats catch-all *. (enforced by: compile-time + runtime)
- More-specific operation-level error entries win over client-level default error entries for the same selector. (enforced by: compile-time)
- Protocol bindings without per-field routing MUST ignore unknown binding modifiers and emit a warning. (enforced by: compile-time)
- The adapter gnomon.lock lockfile MUST be committed to version control and reused when specHash matches the current spec. (enforced by: compile-time)
- The adapter gnomon.lock lockfile MUST be committed to version control and reused when specHash matches the current spec. (enforced by: process)
- The compiler MUST NOT re-query a spec source when its specHash matches the lockfile entry. (enforced by: compile-time)
- The gnomon.lock entry produced by the adapter must be committed to version control so CI builds without network access can compile from cache. (enforced by: compile-time)
- The gnomon.lock entry produced by the adapter must be committed to version control so CI builds without network access can compile from cache. (enforced by: process)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Call Sites
- MUST_NOT — Actuator calls MUST NOT appear in execute {} blocks; they are side-effect-only. (proof citation:
rfc0024_b10_grounded; verification pending) - MUST — All bindings in an execute {} block MUST be consumed in mutations {}, after {}, or as input to other bindings.
- MUST — Each saga step MUST declare both on success and on failure handlers.
The Adapter Protocol
- MUST — An adapter module MUST export the GnomonIoAdapter contract (name and resolve()).
- MUST — The adapter lockfile MUST be committed to version control.
- MUST_NOT — The compiler MUST NOT re-query a spec if the lockfile entry’s specHash matches the current spec hash. (proof citation:
rfc0024_b6_grounded; verification pending)
The client Declaration
- MUST_NOT — A client MUST NOT declare both operations {} and spec:. (proof citation:
rfc0024_b2_grounded; verification pending)
The operation Primitive
- MUST — Protocol bindings that do not support per-field routing MUST ignore unknown binding modifiers and emit a warning. (proof citation:
rfc0024_b0_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0008 |
| Extended by | RFC-0025 |
| Extended by | RFC-0026 |
| Extended by | RFC-0027 |
| Extended by | RFC-0028 |
| Extended by | RFC-0029 |
| Extended by | RFC-0030 |
| Extended by | RFC-0031 |