O1: A Normal Form for Discrete Digital Work

Introduction

Nearly every operation a person or machine can perform on a computer is exposed through a recurring set of surfaces: shell and cloud CLIs, HTTP APIs and OpenAPI services, JSON-RPC methods, smart contract ABIs, IoT device bindings, and model inference endpoints. Everything built on top is a client of one or more. The capability is already deployed and reachable in principle. In practice, a fraction of it is ever used.

Structural costs stand between intent and those operations, on two axes — learning and reach:

The tax is paid per tool, per person, and again after every change. O1 exists to make it a relic of the past.

The Universal Remote. O1 reduces digital surfaces to a single object — the Operation — indexes those descriptions in a shared, content-addressed knowledgebase, and generates the interface for the task rather than for the tool. What follows: one interaction model; possibility before intent; composition across surfaces; the fleet as an operand; knowledge that compounds; and grounded answers that cite live upstream artifacts.

§§1.2–1.5 deepen the learning half; reach, composition, and environment are developed in later chapters.

1.1 Prior art: a short history of interface description

Every generation of computing has tried to make capability reachable without apprenticeship. Each solved the problem one layer up while recreating it one layer out.

On the learning axis, the residue is familiar: invocation gets standardized; description does not. On the reach axis — local horizon, composition, consolidation, the absent environment — the residue is different: there was never a shared object to address, compose, or rehearse against. Both axes are why owned capability stays stranded.

Invocation — the shell

Unix gave every program a common invocation convention — argv, stdin, stdout, exit codes — and a composition operator. That convention is one of the most successful abstractions in computing. But it standardized invocation, not description. --help is a social custom, not a schema. Fifty years on, the fastest way to learn what a program does is still to read prose a human wrote for another human, and there is no machine-readable statement anywhere of whether running it will destroy something.

Definition — the IDL lineage

The next four decades produced a steady sequence of attempts to make interfaces machine-describable: Sun RPC with XDR, CORBA IDL, COM, and eventually WSDL over SOAP. Each defined types, operations, and marshalling well enough for a compiler to generate a client. Each solved definition and stopped there.

UDDI is the sharpest precedent, and the one this document has an obligation to answer. It was a universal, federated registry of machine-readable service descriptions, backed by IBM, Microsoft, and SAP. It is the closest anyone has come to the shape proposed here, and it failed. The diagnosis matters more than the fact:

• Descriptions were authored by publishers as a compliance chore. Nothing downstream failed loudly when they drifted, so they drifted.
• The registry indexed services, not operations a person could run. Finding an entry told you a company existed, not what you could do.
• An entry could not be turned into use without an engineer writing an integration. Registration was the product; use was left as an exercise.

A registry whose entries cannot be executed is a phone book. That constraint governs everything in §3.

The web

HTTP standardized transport. WSDL, then Swagger, then OpenAPI attempted to standardize description, and OpenAPI came closest. Its limits are instructive: it describes request shape well, response shape inconsistently, and consequence barely at all. POST is a routing hint, not a declaration that state changes irreversibly. Security schemes and response schemas are frequently absent in practice, and a document that is present is not thereby correct.

Nodes — JSON-RPC and OpenRPC

JSON-RPC standardized the envelope and said nothing about the method set. OpenRPC supplies the missing description layer and does it well: named methods, typed parameters, typed results, worked examples. Ethereum’s execution-apis document is a first-party OpenRPC specification maintained alongside the protocol it describes, which is rarer than it should be.

Adoption is real and narrow — Ethereum, MetaMask, Starknet, Filecoin, Sui. And there is no APIs.guru for OpenRPC: no aggregated, versioned, machine-consumable index of the specifications that already exist in the open.¹ The descriptions are written. They are not gathered.

OpenRPC also inherits the same silence on consequence. Nothing in the schema distinguishes eth_call from eth_sendRawTransaction. One is free and reversible. The other spends money and cannot be undone. To the specification, they are two methods with typed parameters.

Contracts — the Solidity ABI

Uniquely, this surface nearly got it right. A Solidity ABI is machine-readable, typed, and carries mutability tags — view, pure, payable, nonpayable — that state consequence as a first-class fact. It is the one mainstream surface where a caller can know, before invoking, whether the call can change anything.

That the most adversarial environment produced the most honest interface description is not a coincidence: when misreading an interface costs money irreversibly, description stops being optional.

The ABI’s limitation is scope, not quality. It describes one contract. It says nothing about what the contract is for, which of its functions a person would actually want, or how to reach it — and it is emitted by a compiler for a machine, so the operator’s understanding of why a function matters still lives somewhere else.

Devices

UPnP and Zeroconf solved local discovery. The W3C Web of Things Thing Description made device capability machine-readable and typed, splitting affordances into properties, actions, and events — a good model, and one that maps closely onto the distinctions drawn in §2. Matter standardized a data model across vendors. OpenHAB’s binding library remains the largest practical consolidation of heterogeneous device protocols in existence.

What none of them produced is a device’s capability addressable from outside its own local horizon by the same means as an API call or a contract write. Discovery here is local by construction: SSDP and mDNS stop at the subnet. A Thing Description describes a thing. It does not place that thing anywhere anyone else can reach.

Generated interfaces — model-based UI and the universal remote

There is a research lineage that proposed exactly this and is rarely cited by the people rebuilding it. UIML, the CAMELEON reference framework, and UsiXML all argued that a user interface should be derived from an abstract description of a task rather than hand-built per target. ISO/IEC 24752 — the Universal Remote Console standard — went furthest: any controller renders an interface to any target from an abstract socket description, so a person’s preferred controller becomes the way they operate everything.

That is the same claim this document makes, stated two decades earlier. It did not fail because it was wrong. It failed on authoring cost. Every target needed a hand-written abstract description, and every controller needed a hand-written rendering, and no one was ever paid to write either. The modeling layer was solved and the economics never were.

Generative UI removes that cost. The models were right and arrived before the component that made them affordable. This document’s contribution to that lineage is not the idea of an abstract interface description; it is that rendering one no longer requires a person.

Tools for models

Function calling, and then the Model Context Protocol, addressed the plumbing question: how does a model connect to something that can act. MCP became the de facto answer — adopted across every major provider, donated to the Agentic AI Foundation under the Linux Foundation in December 2025, with more than ten thousand servers published to registries. It is the best answer yet to the question it asks. It is not this question.

Four gaps persist, and they are structural rather than incidental:

• Consequence is prose. A tool description is a string written for a model. Nothing typed separates a read from an irreversible write, so no client can enforce a policy the schema does not express. The Solidity ABI has had this since 2017.

• The unit is the server, not the operation. Discovery converges on server-level identity; tool listing stays on the live connection because a static list goes stale. That is a concession — a durable index of operations is treated as infeasible, so the client gets a pointer to a server it must connect to in order to learn what it can do. Continuous reconciliation of a shared index — treating drift as an event with a subscriber — is §5.

• Authorship is per-server and per-owner. Someone who owns a surface writes a server for it. Surfaces nobody has wrapped stay unreachable, and the long tail is most of the world.

• Nothing persists. What an operator learns about a surface during a session — which parameters matter, which sequence works, what the failure mode looks like — expires with the session. It does not become addressable and it does not accrue to anyone else.

The recurring failure

The recurring failure is the same each time: invocation gets standardized; description does not. Standardizing invocation makes calling cheap for whoever already knows what to call. It does nothing for the person who does not know a capability exists, and nothing to keep one person’s hard-won understanding of a surface from dying in their notebook.

Two things have never been built together:

• Consequence as a typed fact on every surface, not only on the one where mistakes cost money.
• A shared, addressable, persistent knowledgebase of operations spanning surfaces, so that understanding accrues instead of expiring with a session, a registry entry, or a notebook.

1.2 The learning-curve tax

The binding constraint on tool use is rarely missing functionality. It is the cost of reaching functionality that already exists.

Tools do not merely happen to be hard. They systematically:

• Carry noisy schemas — flags, subcommands, option trees, nested property definitions, most of which are irrelevant to any given task.
• Remain mutually isolated, so each new surface demands a new learning curve rather than transferring the last one.
• Keep changing, so learned knowledge decays under version drift.
• Assume a form factor, usually a desktop, and travel badly to anything else.

None of that is the work the operator wanted to do. When onboarding time, syntax overhead, and rote memorization exceed the value of the task, abandoning depth is the rational choice, and the capability stays stranded behind a private apprenticeship.

The consequences compound across an ecosystem: shallow utilization of tools already owned; dialect errors dominating the path from intent to result; human support becoming the product’s real interface; and eventually outsourcing, which concentrates knowledge in specialists rather than compounding it across operators.

1.3 The discovery gap

There is a second, quieter tax, and it is prior to the first. Even an operator willing to climb the curve must first know there is something at the top.

Large language models and natural-language interfaces genuinely advance two things: expression of intent, and execution of an already-known action. Discovery is not advanced by the technology by default. Capabilities remain buried in schema specifications — walls of flags and definitions that obscure a surface before it can ever be invoked.

You cannot ask for what you do not know exists. An interface that only answers intent leaves possibility dark.

This matters more, not less, as models improve. A better model is a better executor of stated intent. It does not widen the set of intents a person is capable of forming.

1.4 The Appliance Paradox

A standing objection: power users adopt arcane tooling voluntarily, so difficulty must be acceptable, or even functional.

It is not. Voluntary adoption of a difficult tool is evidence of unmet demand, not proof that the difficulty was necessary. When a hard tool is adopted anyway, it is adopted in spite of the difficulty. Difficulty selects for survivors; it does not justify the barrier for everyone else who needed the same capability and gave up.

1.5 The Explorer’s Blank Slate

Humans navigate by looking around. We probe edges, we find things we were not looking for, and a large fraction of what we learn about any system arrives that way.

The default single-input prompt box assumes intent is already formed. It neither invites exploration nor supports it. A system that surfaces what is possible — not merely what is asked — converts curiosity into capability and closes both doors of the tax at once: reach and discovery.

Existing approaches and their limitations

Prior unification efforts identified the problem correctly and failed at the last mile: runtime binding, maintenance cost, or semantics. O1 inherits the correct instincts and refuses the failure modes. Each stalled line solved a neighbouring problem — declaration, integration, labour substitution, or invocation — while leaving the portable normal form underspecified.

2.1 Declarative remoting

ISO/IEC 24752 (URC), CAMELEON / MBUI, and the W3C Web of Things articulated remote, declarative interaction with devices and services. The instincts were sound: separate intent from presentation, describe capability once, render many times.

Two things killed them. Authoring burden — writing and maintaining descriptors was itself a job, often larger than using the tool. And no runtime closed the last mile from descriptor to live binding at a cost operators would pay, so the descriptor became another artifact to maintain while the binding stayed bespoke.

O1 keeps the separation of intent from presentation and insists the durable unit be an Operation whose binding is carried at install time rather than hand-written per host.

2.2 Wrapper and SDK unification

Integrators write thin wrappers around each surface. Cost scales linearly with surface count and breaks on every upstream change. The wrapper becomes a second product to maintain, frequently with worse documentation than the dialect it wraps. Every new flag, path, or ABI method is a maintenance event across every wrapper in existence; teams either freeze coverage or staff a permanent translation layer.

Critically, none of it yields a community-contributable, content-addressed descriptor that any runtime could bind. The work does not accumulate.

2.3 RPA and screen-scraping

Automators bind workflows to presentation rather than contract. When the UI moves, the automation dies. The approach optimizes for short-horizon labour savings and against durable semantics.

Presentation-level binding cannot support effect classes, risk declarations, or attestation: without a shared object there is nothing to retrieve, cite, or authorize across surfaces. RPA remains labour tooling. It is not a normalization foundation.

2.4 Tool protocols and agent frameworks

The nearest live neighbours are the Model Context Protocol (MCP), provider-native function calling, and the agent-framework toolkits built on both. They are the most successful attempt yet at the last mile, and O1 depends on their success rather than competing with it. The distinction is narrow, and it is the whole argument.

These protocols standardize invocation. They do not standardize description. MCP specifies how a client discovers a server’s tools, how arguments travel, and how results return. It does not specify what a tool is. Each server author writes a bespoke schema in a bespoke vocabulary. Two servers wrapping the same CLI produce two incompatible descriptions of one capability, and neither can cite the other.

Four limitations follow. Naming them individually matters, because each is repairable in principle and none has been repaired in practice:

• Consequence-blindness. A tool definition carries a name, a description string, and a JSON Schema for arguments. It carries no effect class, no reversibility, no risk. An agent deciding whether a call is safe to make autonomously must infer consequence from prose — and different consumers infer differently, so there is no shared answer to the question “is this a write?”
• Wrapper-equivalence. A tool server for a surface is a wrapper. §2.2 applies unchanged: linear cost, breakage on upstream change, worse documentation than the original. When it breaks, there is no shared corpus for the fix to land in.
• Registry-not-commons. Tools are listed by whoever hosts them and editable by whoever controls the endpoint. There is no content address, no supersession trail, no provenance requirement, no drift signal, and no mechanism by which one author’s work lowers the cost for the next. What is durable is the listing; what should be durable is the description.
• Discovery-blindness. An agent calls what is registered. The operator still cannot ask for a capability absent from the tool list, and nothing surfaces what a bound endpoint could do but nobody thought to wrap. Invocation without normalization does not close the discovery gap — it narrows the aperture to whatever someone already registered.

The relationship is compositional, not competitive. An Operation descriptor can be served over MCP; MCP is a good transport for a normalized unit of work. The reverse does not hold. A tool definition cannot be attested, cited, superseded, or inherited, because it was never required to be more than a call signature. O1 treats tool protocols as consumers of Operations, not as substitutes for the descriptor spine.

2.5 Summary

2.6 Why now

What changed is not the desirability of a normal form — that desire is decades old — but the feasibility of completing runtime binding at invocation while keeping identity, inputs, effect, and risk as declared facts.

A model can complete parameters, adapt presentation, and recover structure from an upstream artifact at invocation time. That removes the authoring burden that killed §2.1 without removing the contract. Models can mediate presentation and parameter completion; they cannot invent a durable contract if the system never required one.

So O1 builds the contract first and applies model mediation only where it reduces authoring cost without erasing semantics.

The Operation

The Operation is the object everything else presupposes. Retrieval cites Operations. Interfaces generate around Operations. Composition sequences Operations. Attestation commits to Operations. Without one object, each layer invents a competing vocabulary for what just ran, and the system loses end-to-end cite, authorize, and attest semantics.

3.1 Definition

An Operation is a discrete unit of work that can be described once, contributed to the knowledgebase, resolved from natural language or ambient context, rendered into a task-shaped interface, and executed through a surface-specific binding.

Three properties are the contract:

• Named. A stable identity that contribution, retrieval, composition, and history can refer to.
• Schema-bound. Inputs are typed before invocation, not reconstructed from free text after failure.
• Discrete. A finished commit: an observer can ask whether it succeeded, what it returned, and which declared effect class it exercised.

Surface dialects remain — they are how the binding reaches the wire. The unit of work does not vary.

3.2 The descriptor

{
  "id": "eth_syncing",
  "description": "Report sync status of the execution client",
  "command": "rpc.eth_syncing",
  "input_schema": {},
  "output_schema": "object|false",
  "effect": "view",
  "reversibility": "read-only",
  "risk": "safe"
}

The descriptor carries a fixed spine. Completeness is not decorative: contribution reject signals treat missing identity, inputs, effect, or risk as incomplete submissions rather than stubs to fill later. Authors and ingest pipelines face the same obligation.

Two things are deliberately absent. Authentication lives in the identity layer (§10), so that every Operation is not forced to re-encode session mechanics. Surface-specific binding lives in the install-time OperationalSchemaBundle, so that the portable claim does not bake in one host’s paths, endpoints, or channel IDs. The descriptor is the portable claim; the bundle is how a particular runtime reaches the wire.

3.3 Effect classes are declared, not inferred

Derivation heuristics exist and are useful: ABI mutability tags, HTTP verbs, RPC write-naming conventions, destructive-pattern detection in CLI help text. They are authoring aids. They are never runtime authority.

The reason is that two consumers must agree on whether an Operation is a view or a write before either renders a confirm step or an agent schedules a chain. Where heuristics disagree with an author’s declaration, the declaration wins, and contribution review treats the disagreement as a signal to fix the descriptor — not as permission for the runtime to guess.

3.4 Resolution and execution

The system exposes three functions. The first two are the counterpart of a state transition function; the third is the one prior systems do not have.

Let K be the knowledgebase, C the ambient context visible on screen, I a natural-language intent, V a set of variable bindings, and B an install-time binding bundle.

Equation 3.3 is the discovery claim in formal dress, and the thing to notice is what is missing from its arguments: there is no I. It takes no intent. Every prior system in §2 implements some version of 3.1 and 3.2 and has no 3.3 at all, because without a normal form there is nothing uniform to enumerate. §7 specifies how the returned list is ranked.

EXECUTE obeys the discrete contract: an invocation either completes under the declared class, or fails in a way that does not pretend a second, undeclared effect occurred.

3.5 A worked example

An operator has a bound Ethereum node behind a load balancer. They believe it may be lagging. They do not know the RPC method name and have never touched systemctl on this host.

The walk-through uses the same overlay operators use: Search, Agent, and Terminal in one pane, with context pinned as inspectable chips. Writes wait. Step through it, or let it play.

Step 0 — SURFACE. Before any intent is expressed, SURFACE(C, K) returns the endpoint’s capability, grouped by effect class: views on the JSON-RPC surface (eth_syncing, eth_blockNumber, net_peerCount, …), writes, and host operations (systemctl.restart, journalctl.tail, df). Possibility is visible without a prompt.

Step 1 — Intent. The operator types in natural language: is this node keeping up? if it isn’t, restart the execution client.

Step 2 — RESOLVE. The query is embedded, classified as hybrid (informational followed by imperative), fanned out across corpus channels, and fused (§6). Ranked candidates include eth_syncing and eth_blockNumber (rpc · view) and systemctl.restart (cli · write · caution). Ambient chips for the bound host (mainnet-exec-01) and the execution client (geth) are injected into the interpretation prompt and rendered on screen as inspectable objects (§8.2). The operator can contest, edit, or pin them.

Step 3 — Interface generation. Type A supplies the normalized Operations. Type B constrains the rendering — conceptual model, error tolerance, inspectability. Type C binds widgets and copy for this invocation. Views run immediately. The write is labelled as a write and waits.

Step 4 — EXECUTE. The write does not run yet. The overlay asks for confirmation: Confirmation required — state-changing action. The operator sees the command (systemctl restart geth) on the bound node (mainnet-exec-01), then Allow or Decline.

Step 5 — Output. The raw result is not what the operator has to read. The selected model renders it through the default output prompt for this surface, or a custom prompt the operator saved. Generative UI is a view of execution — it is not a write into the knowledgebase.

The session crossed two surfaces without the operator learning either dialect, surfaced a capability they did not know to request, named the mutation before committing it, and returned a generated interface for the result. Those four properties are the paper.

3.6 Exclusions as contract

Continuous and live control channels — streaming telemetry, hold-to-move actuation, interactive sessions — violate the discrete contract and are excluded by construction.

This is not a temporary product gap. It is how the normal form stays falsifiable. If an interaction has no well-defined completion boundary, it is not an Operation. If completion is undefined, reversibility and risk cannot be declared honestly, and an attestation cannot point at a finished unit of work. A system that quietly admits continuous channels has no remaining semantics: composition, risk, and attestation would stop meaning one thing each.

Those channels may exist beside the system as substrate facilities. They are not candidates for the spine.

Surface normalization

Each surface is an instance of populating the descriptor. Fidelity varies: some fields are given by the upstream artifact, some inferred, some carried only in the binding bundle, some lossy or inexpressible. Lossy cells are first-class and flagged, because honesty about information loss is part of the normalization claim.

4.1 A fidelity metric

Let F be the eight spine fields. For a surface instance s, each field is scored:

Class fidelity is the mean over a sample:

Sample sizes, sources, sampling method, sample date, and the per-field breakdown are in Appendix B. Numbers without that appendix should not be believed, including ours.

4.2 The matrix

Each row is a class mean. The reductions below are canonical instances scored under (4.1) — σ = 1 given, 0.5 inferred, 0 unavailable — so the matrix columns have something to point at. They are not Φ_class.

CLI. Help trees parse into a CLIHelpDoc and leaf CliCatalogOperation. Given: command path, many flag names, leaf identity once parsed. Inferred: types, defaults, effect, risk. Lossy: nested option interactions, positional ambiguity, undocumented side effects. What help does not say remains unbound — never silently invented. CLI is the canonical noisy schema; the normalizer’s job is to extract a discrete leaf, not to reproduce the option tree as the interface.

Let s = reth stage drop ⟨stage⟩. Help sets σ(id) = σ(command) = 1. Flag types, effect, and risk are authoring aids: σ = 0.5. Nested interactions (drop vs unwind vs run) are distinct leaves or stay unbound (σ = 0 where help is silent). The extracted Operation is a write · reversible · caution. The option tree is not the interface.

REST / OpenAPI. Given: path, method, parameters, request-body shape after $ref resolution. Inferred: effect from verbs, risk from destructive method patterns. Lossy: response schemas and security schemes, dropped relative to a full document.

Let s = POST /repos/{owner}/{repo}/issues. Path, method, and {owner} / {repo} are given (σ(input) = 1). Effect follows the verb: write, by convention, never by runtime guess (σ(effect) = 0.5 until declared). Response schema and security schemes are dropped: σ(output) = 0 relative to the full document. High request-shape fidelity, low consequence fidelity — the inverse case of §4.3.

OpenRPC / JSON-RPC. Given: method name and declared mutability where the catalog provides it. Inferred: write versus view from naming when tags are incomplete. Lossy: parameter and result schema, effectively opaque. Subscribe-class methods implying continuous streams are excluded unless wrapped as discrete calls.

Let s_view = eth_syncing and s_write = eth_sendRawTransaction. Identity and mutability are given (σ(id) = 1, σ(effect) = 1 where tagged). Input and output stay opaque (σ ≈ 0) until EXECUTE binds against the live endpoint. eth_subscribe has no completion boundary and is excluded unless wrapped. Lowest Φ_class, first market: identity and mutability are what discovery and authorization actually consume.

Solidity ABI. Given: selectors, argument types, mutability tags. Inferred: risk and reversibility refinements beyond the coarse tag. Lossy: semantic intent absent from types alone — what a bytes argument means. The contract surface is unusually friendly because the artifact is already a typed interface.

Let s = transfer(address,uint256) tagged nonpayable. Selectors and types are verbatim: σ(input) = σ(output) = σ(effect) = 1. Semantic intent — whose tokens, why — is not in the types. Highest Φ_class because consequence is a typed fact, not because purpose is.

IoT via OpenHAB. The chain Page → Item → Channel → Binding → Protocol → Device, with live enrichment, maps physical capability into discrete Operations. O1 drives OpenHAB as a binding dependency; it does not reimplement BLE/RF physics. Lossy: continuous telemetry and hold-to-move actuation, which remain substrate facilities.

Let s = Light_Kitchen on a Switch channel. ON / OFF is a discrete write; a sensor read is a view. Live enrichment can raise σ(input) above a static Thing Description. A dimmer ramp has no result R for EXECUTE(O, V, B) and is not a candidate.

AI models. Discovery via Ollama and OpenRouter yields model identity and catalog metadata. Lossy: full capability cards and prompt-behaviour guarantees that no static schema can pin.

Let s = deepseek-chat via OpenRouter. Identity is a snapshot (σ(id) = 1 at crawl time). A completion is a discrete Operation; the prompt-behaviour card is not a schema. Φ here measures catalog recoverability, not that the model will do what the card claims.

4.3 Fidelity is not suitability

The most important thing in this section is a distinction the matrix alone will mislead you about.

Φ measures how much of the spine survives reduction. It does not measure suitability for safe execution, and the two can move in opposite directions.

JSON-RPC scores lowest, and JSON-RPC is our first market. That is not an oversight. What RPC gives is identity and mutability — precisely the fields discovery and authorization depend on. What it withholds is parameter and result schema, which is precisely the part runtime binding completes against a live endpoint.

The inverse case is the dangerous one. A REST surface with a complete request schema and no declared consequence has high schema fidelity and low decision value: a consumer knows how to shape the call and not what the call will do. Solidity ABIs score highest because they are the one mainstream surface that treats consequence as a typed fact.

This is why §3.3 requires effect and risk to be declared rather than inferred, and why the beachhead is where it is.

The grounded knowledgebase

The knowledgebase is real-time and real-world, not a frozen training corpus. It is the compounding asset against which retrieval resolves, interfaces generate, and contributions attest. Parametric memory paraphrases what it once absorbed; the knowledgebase holds citeable artifacts that still exist upstream.

5.1 Ingestion

Production crawlers ingest the sources operators already treat as authoritative: documentation sites; GitHub releases, READMEs, issues, and markdown trees; maintainer channels where behaviour gets clarified before it reaches documentation; package registries; APIs.guru OpenAPI catalogs; chainid.network; Thirdweb and Etherscan ABIs; OpenHAB bindings; cloud pricing APIs; HuggingFace and OpenRouter model metadata; curated OpenRPC families.

Each source class is a provenance channel, not undifferentiated text mixed into one bag of chunks. Upstream published_at / updated_at stamps travel with the artifact so freshness stays attributable.

Ingestion is not training. The goal is durable, citeable records of tools as they ship and change, so retrieval can ground a claim in a specific release note, schema revision, or ABI digest instead of inviting a model to reconstruct one from recall. Release notes are embedded as first-class evidence, because operators usually need the delta, not the latest man page.

5.2 Content addressing

Identity follows bytes, not filenames or editorial convenience. Per-tool version manifests record {path, content_hash} pairs under SHA-256; a root manifest hash commits the set:

Preferred-version tagging selects which lineage retrieval should prefer without erasing siblings. Identical content collides to the same address; supersession is an explicit act leaving both addresses auditable. Diff statistics over manifests make drift observable as a structural change rather than a subjective judgment that the docs feel different.

Onchain, catalogHash carries the CID of a catalog commitment, and outputHash serves as execution proof where an Operation produces attestible output. The chain therefore holds commitments; the corpus holds artifacts.

5.3 Versioning and drift

Version families track CLI, OpenAPI, contract, RPC, IoT, and AI model lineages as parallel histories rather than one rolling “latest,” with release-note chunks beside them so a query about a breaking change can cite the cut that introduced it.

Freshness discipline separates two watermarks that are commonly conflated:

• coverage_as_of — when the collector last looked.
• insights_as_of — when the world last changed.

How recently we looked is never treated as how recently the world changed.

Drift is a first-class signal. A binding whose live bytes no longer match its content address is stale, not close enough, and retrieval surfaces the mismatch rather than smoothing it over with fluent paraphrase. Operators inherit a vocabulary for disagreeing with the corpus — hash mismatch, watermark age, preferred-version lag — instead of a binary “the knowledgebase said so.”

5.4 Contribution

Submission requires a complete descriptor — identity, inputs, effect, reversibility, risk, binding hints — plus provenance of the upstream artifact it claims to describe.

Reject signals are contractual rather than taste-based:

• incomplete schemas
• unverifiable provenance
• effect or risk misdeclaration
• duplicate content-address collisions lacking an intentional supersession trail

Curation and quality signals — freshness, usage, attestation — rank what retrieval prefers without rewriting history. New addresses append. Supersession leaves a trail. Nothing is edited in place in a way that would make a prior citation lie.

5.5 Durable asset versus commodity runtime

Operators, gateways, and UI shells age with frameworks, hosting choices, and interaction fashions. The content-addressed corpus does not: the same hashes, manifests, and descriptors remain addressable after any particular shell is discarded.

The asymmetry is intentional. Interfaces may be regenerated; runtimes may be swapped; the knowledgebase outlives the interface sitting on top of it. Treating the corpus as the compounding layer and the runtime as expendable scaffolding keeps investment where it accrues.

Resolution: grounded retrieval

Resolution turns intent into citeable evidence over K. Parametric memory is useful for fluency and for narrating evidence. It is not the ceiling on what may be known.

6.1 Pipeline

Query preprocessing and embedding (OpenRouter by default, text-embedding-3-small, cached so identically worded intents do not re-embed). Then intent classification routes into one of:

Classification selects which corpora deserve weight. It does not select which facts the model is permitted to invent. A man-page paraphrase and an Operation descriptor answer different questions even when their embeddings sit nearby, which is why hybrid intents fuse rather than flatten.

6.2 Channel fanout and reciprocal-rank fusion

Eight corpus channels — cli, blockchain, cloud, iot, ai, smart-contract, api, general — are probed in fanout. Each returns its own ranked list. Lists fuse by reciprocal-rank fusion:

where $w_c$ is the per-channel weight, adjustable by per-intent override.

Fusion rewards items that agree across channels while damping a single noisy corpus that happens to rank something highly in isolation. $K = 60$ is the classical constant from Cormack et al.: it softens rank position without letting deep tails dominate.

The architectural claim is modest and consequential: grounding is a multi-corpus agreement problem before it is a generation problem. When channels disagree, the fused ranking carries channel provenance forward, so consumers see which surface produced which candidate rather than receiving a flattened top chunk with the disagreement erased.

6.3 Scope narrowing

Source-type caps, deduplication, token-budget trim, cross-channel collision guards, and explicit-hint ranking keep the evidence window usable rather than merely large.

Disambiguation is a retrieval problem before it is a generation problem: better candidates beat longer prompts. Caps prevent one source type from exhausting the budget. Deduplication collapses near-identical hashes and paraphrases. Collision guards stop one artifact appearing under conflicting channel labels without disclosure. Explicit hints — pins, surface context, operator selections — outrank ambient similarity when the operator has already narrowed the world.

6.4 Real-time grounding

Some channels decay on operational timescales and are refreshed accordingly: cloud pricing on a five-minute cadence, ticker movers, IoT live enrichment, model usage stats. These do not replace content-addressed documentation; they answer questions documentation cannot — what a SKU costs now, what a sensor reports in this moment.

6.5 Weights are policy over evidence

Channel weights bias fusion toward domain-appropriate corpora: elevated blockchain and catalog channels for chain-native intents, man-page weight for CLI.

A weight is policy over evidence, not a license to invent missing channels. A zero-weight channel is skipped, not hallucinated. Changing a weight changes which evidence is preferred; it does not mint facts no channel returned. That separation is what keeps retrieval honest when intents shift.

6.6 On training cutoffs

Fluency without retrieval is bounded by training. Fluency with retrieval is bounded by corpus coverage, freshness watermarks, and fusion policy — three bounds an operator can audit.

Fluency without retrieval is bounded by training. Fluency with retrieval is bounded by corpus coverage, freshness watermarks, and fusion policy — three bounds an operator can audit. Retrieval defeats a training cutoff only where the corpus actually reaches.

Discovery

Equation 3.3 takes no intent. That makes ranking harder, not easier, and this section owes the reader a mechanism rather than a claim.

7.1 The problem

Query-conditioned retrieval has an anchor: the query. Unprompted surfacing has none. The question SURFACE(C, K) must answer is what should this operator see that they did not ask for, given only what is on screen.

The naive answers are both wrong. Surfacing everything is not discovery — it is the original noisy schema with better typography, and it reproduces exactly the wall of flags §1.2 describes. Surfacing the most popular Operations re-buries the rare capabilities that motivated the system in the first place.

7.2 Surfacing

Candidates are drawn from the Operations bound to the surfaces present in C, then ranked on a combination of:

• Bindability — is this Operation executable right now against a bound surface in C, or does it require material the operator does not have? Unbindable capability is noise.
• Effect stratification — views and writes are surfaced as separate strata rather than interleaved, so the safe set is legible at a glance and the mutating set is never scanned past accidentally.
• Contextual adjacency — Operations that historically co-occur with the entities already on screen.
• Rarity correction — a term that deliberately opposes pure popularity ranking, so that a capability’s obscurity does not compound its invisibility.

The ranking function and its parameters remain an open problem we would rather name than hide. We state the shape of surfacing here and keep the coefficients out of the claim until they can be defended.

7.3 Why this cannot be bolted onto a tool registry

Enumeration presupposes uniformity. A registry of bespoke schemas can list what has been registered; it cannot enumerate what a bound surface affords, because there is no uniform predicate to evaluate. Discovery is downstream of normalization, which is why §2.4’s systems do not have it and could not add it without first solving §3.

The generative interface

Interface generation closes both of Norman’s gulfs. The gulf of execution is the distance between goal and available action. The gulf of evaluation is the distance between system state and the operator’s ability to interpret what happened.

A generative layer that fills only the first — producing fluent controls over an opaque outcome — recreates the appliance paradox in natural language. Generation is therefore constrained so that fluency never substitutes for intelligibility.

8.1 Type A / B / C decomposition

The stack is an order of dependencies, not a menu of styles. Both B and C presuppose A. Without A, generation has nothing durable to bind to and every invocation reinvents the Operation from ambient prose.

Conformance means B’s constraints are enforceable rather than left to the model’s taste per invocation. Generation may choose among conforming realizations; it may not invent a surface that discards an Operation’s declared shape or hides the context it depends on.

8.2 The intelligibility constraint

You should always be able to see why the system is about to act.

Context the agent uses — the bound node, the RPC surface, a pinned contract — is rendered as inspectable chips, not hidden inside a prompt. If a chip is on screen, it is part of the shared situation. If it is missing, the system must not pretend that entity was known.

That is the contract for operators: contest, edit, or pin context before a write runs. Silent fusion of context is not a convenience. It is a failure mode. You cannot correct what you cannot see, and an agent cannot be blamed for acting on premises it never showed you.

8.3 Context as the base layer

App and domain data already visualized constitute a base layer for every prompt and agentic step. The GUI is not merely a display; it is a live inventory the generative layer may draw on without forcing the operator to restate what is already on screen.

The ambient payload stays thin by default, with explicit pins for precision. Oversized ambient dumps dilute ranking, invite mis-binding, and make the inspectable-chip contract harder to honour because nothing important remains visually distinct. Thin-by-default is a retrieval and intelligibility choice, not a minimalist aesthetic.

Surfaced context is composable across successive Operations: subsequent steps inherit and extend it. Discovery and reuse are the same mechanism seen from two angles — what the chips reveal for the first step remains available as input for the next.

Composition and programmability

Programmability splits into an execution surface and a knowledge surface — the same two the product uses internally.

Execution (Backend OpenAPI). Nodes, Applications, Addons, Monitoring, Realtime, Deployments, Environments, Storage, Settings, Operations, Sync, Health, Explorer. Authenticated by administrative bearer or issued API keys. A program can provision a node, declare and deploy an application, run an Operation, stream logs and metrics, and read operation history — the same control plane the interface exercises.

Knowledge (Gateway). Grounded retrieve, tool listing and execution, command recommend, CLI help and search, explorer catalogs, model listing, semantic answer, SIWE auth.

Publishing the control plane does not weaken it. Effect classes, inventory identity, and tenant isolation bind whether the caller is a button or a bearer token. What it removes is the fiction that automation requires a parallel, less governed path.

Agent tool register. Gateway and backend capabilities are wrapped as typed function specs. The agent can self-describe the backend (list_backend_ops → get_backend_op_schema → invoke_backend_op) without hard-coded integrations per resource family. New OpenAPI operations become invocable when their schemas are listable, rather than when someone ships a frozen plugin. The register is a discovery surface over live contracts, not a curated menu that ages independently of what it wraps.

Composition. Ordered steps chain across cli, api, rpc, abi, iot, ai. The OperationalSchemaBundle packages multi-surface artifacts into one deployable unit. An Observe–Think–Act loop enforces step limits and doom-loop guards and emits typed markers (<!--TABLE-->, <!--STATS-->, <!--LIST-->, <!--TAGS-->) so structured results stay machine-consumable across turns.

Cross-surface ordering respects each Operation’s effect class. Composition is permissioned sequencing.

Extensibility. Bring-your-own model endpoints including self-hosted Ollama; custom API servers with live OpenAPI fetch; pluggable storage drivers (filesystem, Mongo, S3, Redis). BYO extensibility is the dual of content-addressed contribution: the corpus grows by accepted descriptors, the runtime grows by declared endpoints speaking the same contracts. Neither waits for a central catalog to bless a private tool.

Identity and authorization

Authentication establishes a principal. Authorization decides what that principal may touch. They are layered so a breach in one plane does not trivially escalate into another.

Human identity — SIWE. A random nonce binds the signature to a fresh challenge so replay cannot mint a live session; verification recovers the secp256k1 public key, which becomes the JWT subject; revocation is a session-store operation. There is no password corpus to defend, and wallet custody changes leave nothing to scrub.

Machine identity. API tokens from 32 random bytes, stored scrypt-hashed, compared in constant time, plus an administrative bearer for break-glass control-plane access. Rotation invalidates the prior hash. Compromise of one key does not imply compromise of SIWE sessions, and compromise of a session does not mint infrastructure keys — different revocation paths by design.

Transport. Ed25519 preferred, RSA-4096 fallback, per-tenant key namespaces. SSH remains the only required listener on managed nodes. Which key may open which node is a declared inventory fact, not an emergent property of a daemon mesh.

Data. Cloud credentials at rest under AES-256-CBC; user volumes encrypted at the storage layer; secrets scoped to the owning tenant. Backup and rollback inherit the same assumptions.

The fourth row is what normalization adds. A valid session that may view is not thereby entitled to every write. Authorization can reason about the work itself, not only about who presented a credential.

The Operator

Operations reach real machines. The control plane that does that work is deliberately boring: SSH, Ansible, and the substrates you already run.

There is no proprietary agent daemon on the node. Reach is SSH. Orchestration is Ansible. Substrates are systemd, Docker, and Kubernetes. If you already know how to harden sshd and read a playbook, you already know the execution path.

SSH — agentless reach. Managed nodes expose sshd only. Compromise response is the playbook operators already run — revoke keys, reconcile inventory, re-enrol — not a hunt for proprietary agent state.

Ansible — orchestration. Desired state is declarative and idempotent. Re-running converges rather than appends. Roles and collections stay foundational technology, not a proprietary mover we would have to staff forever.

Three substrates, one declaration. systemd units and journald; Docker Compose and daemon logs; Kubernetes and Helm where cluster semantics fit. The Operator picks the substrate; Ansible carries the reconcile.

Provisioning. Adapters for AWS, GCP, Azure, DigitalOcean, and Latitude create or reuse compute. Spot-heal relaunches instances while keeping attached disks, so ephemeral failure does not imply durable data loss.

Observability by harvest. O1 does not invent a second telemetry plane. It reads what substrates already emit — journald, container logs, host metrics, Prometheus o1_* gauges, and live WebSocket/SSE/PTY streams during execution.

What O1 does not own. Bindings stay replaceable. OpenHAB covers device radio; serving/CDN sits at the outermost hop; upstream state stays where it belongs. The durable layer is the Operation, not the transduction beneath it.

State of record. YAML inventory (nodes.yml), per-tenant namespaces, multi-driver storage with atomic writes and backup/rollback. The inventory is what the Operator reconciles against — not a dump of live drift.

Protocol

The onchain layer attests ownership, contribution, and emission without relocating the knowledgebase into a proprietary vault. Content addresses and descriptors remain offchain artifacts; the chain records commitments, namespace rights, and claim splits that must be globally consistent.

12.1 Why a chain at all

OpenAPI, npm, crates.io, and Homebrew are commons that compound without tokens. Content addressing already gives durability. The chain exists for what those layers cannot: transferable, rentable, splittable curation rights over a namespace, and attribution that survives the operating entity.

A registry editable by whoever controls the DNS name is a vendor catalog with good manners, not a commons. Under a foundation model, contribution credit dies with the foundation.

The chain does not make descriptors true, prevent drift, or adjudicate quality. Those remain offchain. What it records is what must stay globally consistent: commitments, namespace rights, and claim splits.

12.2 Four contracts

Responsibility is split so that token supply, treasury vesting, namespace ownership, and contribution attestation cannot collapse into one mutable admin surface.

Separating these makes privilege boundaries legible: mint policy cannot rewrite namespace tenancy, registry rentals cannot mint supply, DCO scoring cannot vest treasury buckets. Holders reason about failures within a contract’s mandate rather than against an omni-admin proxy.

12.3 DCO lifecycle

COMMITTED ──settle──▶ SETTLED
    │
    └──timeout──▶ TIMEDOUT   (streak := 0)

A contributor commits attested work against a declared weight. Settlement confirms within the epoch rules. Timeout clears unsettled commitments and zeroes the consecutive-epoch streak, so continuity is earned rather than assumed.

finalizeEpoch remains O(1) at the epoch boundary — no quadratic scan of history. Claims split 70/20/10 among owner, executor, and treasury, aligning catalog ownership, the party that performed execution work, and protocol runway.

The state machine is both an incentive schedule and an audit trail: unsettled work does not silently accumulate score, and timeout is a first-class outcome rather than an implicit failure buried in offchain logs. Equation 12.1 is linear in consecutive epochs; that unbounded streak is a known incentive weakness we flag rather than hide.

12.4 Namespace ownership

Namespaces are ERC-721 assets with ERC-4907 rental semantics. Tenant and user roles keep curation portable when the person maintaining a surface is not the entity holding the NFT: ownership can move without forcing every curator to be the capital holder, and rental can end without rewriting content addresses under the namespace.

USDC subscription prices namespace economics in a unit operators already budget in, rather than forcing tenancy to track token volatility.

Ownership moves; content addresses do not have to. The registry separates rights to a name from the hashes of the artifacts that name organizes — an essential separation if the corpus is to remain durable while control of a catalog root changes hands.

Token and issuance

The token prices attested contribution and weights governance over onchain-verified attributes. It is not required to read the commons.

13.1 Supply

21M hard cap: 9M genesis to treasury, up to 12M mined via DCO. The cap is a commitment that vesting and emission cannot mint around.

The 21M cap is a deliberate fixed-supply commitment, not a derived equilibrium. What is load-bearing is the split: 9M genesis (the treasury buckets above) versus 12M mined. Vesting and emission cannot mint around the cap.

The cliffs on ecosystem and team delay unlock until protocol surfaces have had time to stabilize. Investor vesting is shorter, reflecting earlier capital risk while still avoiding instant liquidity that would dominate early governance weight. The DAO bucket keeps a minimum pool for holder-directed work — bounties, audits, curation — without raiding mining emission or access fees.

13.2 Emission

Let $r = 98849/100000$ be the per-epoch retention factor and let an epoch be 30 days. Emission in epoch n is proportional to $r^n$; total issuance converges to the 12M allotment.

Three readings of the same constant:

The half-life is the intuitive form: a smoothed halving on a roughly five-year cadence, with no discretionary vote at each step. Remaining issuance is computable by any participant from two published values.

Combined with the streak term in 12.1, sustained early contribution is comparatively scarce later. Late entrants are excluded from the densest emission years, not from settlement.

13.3 Separate ledgers

Hosted Operator tiers settle in stablecoin or fiat off-chain. Namespace economics settle in USDC.

Separating mining economics from access fees prevents the commons from being gated by speculative price while still funding contribution through emission. An operator can consume grounded knowledge without mining; a contributor can mine without purchasing a seat.

The ledgers meet at governance and attestation — not at every read path. When they do meet, the join is explicit: emission funds work that entered the catalog under published rules; access fees fund runtime capacity. Neither ledger is asked to impersonate the other.

Expanding the token to “must hold to read” would convert a commons into a toll booth and contradict the central claim of §5.5. The token prices contribution and ratification, not curiosity.

Applications

You already do this work. O1 makes it reachable — servers, APIs, chains, devices, and models — without a private apprenticeship in each tool.

Governance

Governance specifies who decides what, on what cadence, and under which phase — without conflating protocol ratification with day-to-day operations.

15.1 The decision surface

Holder-governed. Catalog hashes defining canonical corpus commitments; DCO approvals and emission weights; treasury splits. These rewrite shared economic or epistemic ground truth and require ratification against published thresholds.

Operating-entity retained. Runtime images, hardware provisioning, sensor wiring, interface UX, incident response — anything that does not alter an onchain-verified attribute. These stay operational so the control plane can heal and ship without quorum on every patch.

When an operational change would mutate an onchain-verified attribute — a corpus republish that updates a catalog hash — the attribute change is the governance event, not the deploy. The boundary exists so that cost of capture and cost of inertia can be reasoned about on the right surface. Putting uptime votes onchain uses the wrong instrument; putting catalog truth in an admin key defeats attestation.

15.2 Proposal lifecycle

Publish. Proposal text and target attribute commitments posted with the applicable quorum and threshold class. Discuss. Holders and operators examine emission, registry, and catalog consequences; amendments remain possible. Ratify. Weight is cast. Success commits the new attribute state; failure preserves the prior commitment.

There is no silent upgrade path for catalog-hash or DCO-weight changes. Thresholds are published with the proposal surface, so participants are not asked to invent figures at ballot time.

15.3 Progressive decentralization

Later phases expand who may run trusted movers. They do not rewrite the Operation or knowledgebase contracts. Speaking of Attested or Distributed in the present tense would be an overclaim; the honest present tense stops at Steward.

Security and trust model

16.1 Threats

• Malicious Operation submissions — forged provenance, under-declared effects, or payloads seeking emission credit without honest work.
• Binding drift — an ABI revision, flag rename, or device capability shift that leaves a content-addressed artifact looking current while the live surface has moved.
• Over-scoped authentication — a valid session or token exercising write classes never granted to that principal.
• Model-mediated misresolution — fluent but ungrounded selection of the wrong Operation or parameters; ranking that sounds correct while citing nothing.

16.2 Mitigations

Where a control cannot eliminate a threat, it makes the mismatch detectable or the authority narrower. It does not claim omniscience.

Conclusion

The thesis of this paper is that the missing object in tool interfaces is a description, not a protocol — and that once description is one kind of object, the reach axis becomes solvable too.

Fifty years of interface work has repeatedly standardized invocation while leaving description to social convention. That choice makes calling cheap for whoever already knows what to call, and it leaves the learning axis untouched: dialect, discovery, private apprenticeship, syntax, and frozen knowledge. Contemporary agent stacks inherit those costs, because they standardize the transport of a call and not the description of a capability. The reach axis — local horizon, composition, forced consolidation, the absent environment — was never even in scope for invocation protocols: there was no shared object to address, compose, or rehearse against.

O1’s claim is that a single normal form — named, schema-bound, carrying effect and risk as declared facts — is enough to close both axes. Once discrete work is one kind of object, it can be enumerated without a query, retrieved with citations, rendered for the task rather than the tool, composed across surfaces without changing languages, addressed as a fleet rather than a session, and attested so that one operator’s understanding raises the floor for the next. Syntax, consolidation, and the absent environment dissolve once those six are in place.

Two things follow that we think are more durable than the runtime. The knowledgebase compounds while shells and agent binaries age out. And the discipline of declaring consequence before executing gives authorization something to reason about besides who presented a credential.

The system is on testnet. The specification is open, the corpus is free to read, and the parts we have got wrong are more useful to us in the open than in a drawer.

Terminology

References

1. Buterin, V. (2014). Ethereum: A Next-Generation Smart Contract and Decentralized Application Platform. https://ethereum.org/whitepaper/
2. Wood, G. (2014–). Ethereum: A Secure Decentralised Generalised Transaction Ledger (Yellow Paper).
3. Norman, D. A. (1986). Cognitive Engineering. In User Centered System Design. — gulfs of execution and evaluation.
4. Bellotti, V. & Edwards, K. (2001). Intelligibility and Accountability: Human Considerations in Context-Aware Systems. Human–Computer Interaction 16(2–4).
5. Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods. SIGIR ‘09.
6. ISO/IEC 24752. Information technology — User interfaces — Universal remote console.
7. Calvary, G., Coutaz, J., Thevenin, D., et al. (2003). A Unifying Reference Framework for Multi-Target User Interfaces (CAMELEON). Interacting with Computers 15(3).
8. W3C. Web of Things (WoT) Thing Description. https://www.w3.org/TR/wot-thing-description/
9. Anthropic. Model Context Protocol Specification. https://modelcontextprotocol.io
10. OpenAPI Initiative. OpenAPI Specification. https://spec.openapis.org
11. Entriken, W., Shirley, D., Evans, J., Sachs, N. ERC-721: Non-Fungible Token Standard. https://eips.ethereum.org/EIPS/eip-721
12. Anders, A., et al. ERC-4907: Rental NFT. https://eips.ethereum.org/EIPS/eip-4907
13. Adams, H., Zinsmeister, N., Salem, M., Keefer, R., Robinson, D. (2021). Uniswap v3 Core. https://uniswap.org/whitepaper-v3.pdf
14. O1 Labs. O1 Litepaper. ‹url›

Appendices

Five supporting notes, published as they are completed. Nothing below is a substitute for the sections it cites.