Operations and outcomes

An operation is the owned callable contract: one nominal identity, one input, one result, declared domain faults, effects, deadlines, cancellation, idempotency, authority, and evidence obligations. The CLI, Rust and peer-language SDKs, HTTP and messaging projections, UI actions, and automation all project the same operation identity; a projection never redefines it.

Author a product teaches how to declare an operation and Services and APIs explains how to design one. This page is the stable clause reference and the outcome vocabulary the rest of the site links to.

Two canonical declaration forms

The head that declares an operation belongs to the selected semantic domain. Two forms are demonstrated today.

Contracts (one.contracts@1) declares a top-level dotted operation and a service that exposes it:

One

operation Orders.Get@1
    accepts OrderKey
    returns OrderView
    faults OrdersGetFault
    effect read
    deadline 1s
    invocation direct
    requires one.data.state#Read@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )

service Orders@1
    expose Orders.Get

Product (one.product@1) declares a service whose members are operations:

One

service Orders@1
    operation get
        input OrderKey
        returns OrderView
        faults OrdersGetFault
        effect read
        deadline 1s
        requires one.data.state#Read@1( resource: parcelhub.orders scope: fields(customer_id, order_id) )

Choose the form that belongs to the item's selected domain. The two forms are not merged and cannot be mixed inside one item. query and command service members are illustrative target syntax, not implemented heads; a bare dotted operation is the only canonical operation identity.

Clause reference

Clause	Meaning	Status
`operation Namespace.Member@1`	Contracts operation identity; dotted before the lane	demonstrated
`service X@1` + `expose Member`	Contracts service exposing member operations	demonstrated
`service X@1` + `operation <name>`	Product service with operation members	demonstrated
`accepts <Schema>` / `returns <Schema>`	Contracts input and result schemas	demonstrated
`input <Schema>` / `returns <Schema>`	Product input and result schemas	demonstrated
`faults <Fault>`	One declared fault schema	demonstrated
`effect pure`, `effect read`, `effect irreversible`	Effect class of the operation	demonstrated
`effect replay safe`	Activity effect class inside a workflow	demonstrated
`deadline <quantity>`	Finite execution bound such as `250ms`, `1s`, or `15m`	demonstrated
`invocation direct`	Root-local dispatch contract	demonstrated
`idempotency operation(window: <duration>)`	Replay window for an operation-level deduplication identity	demonstrated
`idempotency caller_key(...)` / `provider_key(...)`	Caller- or provider-keyed deduplication	intended
`outcome query <Operation>`	Read that resolves a dispatched attempt whose response was lost	intended
`requires <Capability>(...)`	Provider-independent capability requirement	demonstrated
`authority <Identity>`	Domain-defined authority requirement	demonstrated in provider and workload domains
`secret <name>: <Type>`	Symbolic secret requirement, never a value	demonstrated in provider and configuration domains
`state <Contract>` block	Typed state lane the operation may use	demonstrated

A clause the selected domain does not govern fails with an exact diagnostic; it is never ignored or guessed. See the .one source language for canonical spellings.

Faults stay separate from failure

A fault schema is a named, owner-qualified value whose variants are unit variants today. A payload variant such as invalid_catalog_item(sku: Sku) is illustrative target syntax. A fault is a declared business outcome of the operation:

admission or policy denial is not a fault;
cancellation and deadline exceeded are not faults;
unavailable, incompatible, and provider failures are not faults;
an outcome unknown after dispatch is not a fault;
a violated invariant or malformed response is a defect, not a fault.

Only a declared fault may be handled as a domain outcome. The full class list is in the failure model.

Effects, idempotency, and outcome queries

Declaring an effect states what the operation may do at its boundary; it does not grant authority: requirements are not grants.

Every mutating operation states how a repeated or uncertain attempt is resolved. A caller-key or provider-key contract binds deduplication to that key with an explicit window; an outcome query names the read that reveals the result of an attempt whose response was lost. An operation that declares neither is honestly non-idempotent and must suspend or reconcile rather than auto-retry after dispatch.

Deadlines, cancellation, and requirements

A demonstrated operation names a finite deadline. Cancellation and timeout describe the caller's knowledge, not the external world's state. Dropping a future is cancellation, not rollback.

A requires clause is a provider-independent requirement inferred for one root. Planning selects the exact realization that satisfies it; the requirement itself is not a provider choice or a grant. See roots and composition and providers and adapters.

The outer outcome vocabulary

Every invocation resolves to exactly one outer class. Language projections may adjust letter case, but they map one-to-one to these names and must not invent a synonym; Succeeded is the only success variant. A per-operation domain fault is carried by Rejected and never becomes an outer class of its own.

Group	Classes
Semantic	`Success`, `Domain fault`, `Rejected input`, `Conflict`
Authority and admission	`Denied`, `Indeterminate`, `Expired`, `Untrusted`
Execution and communication	`Cancelled`, `Deadline exceeded`, `Resource exhausted`, `Incompatible`, `Unavailable`, `Outcome unknown`
Composition and realization	`Unsupported`, `Unsatisfied`, `Ambiguous`, `Missing evidence`, `Stale evidence`
Defect	`Defect`

An action that may have crossed its boundary returns Outcome unknown until reconciled. It is never converted to failure so that a duplicate can be sent. See Handle failures without flattening them for the exhaustive match.

One operation, many boundaries

An operation does not imply a network. Planning may realize the same operation as a static call, a task, a local process, a remote request, or an external managed capability, and each descent adds only the codecs, identity, authorization, deadlines, delivery, backpressure, observation, and cost that boundary requires. A transport success is never a domain success. See Communication.

Versioning is directional

Orders.Get@1 names the @1 compatibility lane; one.lock resolves it to one exact immutable revision. Keeping the name and lane does not by itself make a new revision compatible with its producer, consumer, stored data, or in-flight workflow. A breaking change is an explicit revision with a planned coexistence or cutover. See Change and evolution.

Executable evidence

The checked-in examples below declare, implement, and exercise operations through the ordinary lifecycle:

Hello's pure unary operation and one native implementation claim: examples/hello/one.
ParcelHub's Get/Place/Cancel operations, domain faults, idempotency, and typed state lanes: examples/parcelhub/one/contracts.one.
Support Triage's operations, workflow, and bounds: examples/support/triage/agent/one/support-triage.one.
Order Review's Product service with an operation member: examples/order/review/web/one/contracts.one.

Invoke one exact root-reachable operation with a schema-checked request document:

Console

one invoke <operation-id> request.json

Normative owner & evidence

Contracts owns the operation, fault, effect, idempotency, and outcome meta-contracts; Components owns operation and service composition; each namespace owns its operation instances. Planning and Deployment own binding, authority, and reconciliation.

Demonstrated today: the Contracts and Product operation forms, unit fault schemas, pure/read/irreversible effects, finite deadlines, invocation direct, idempotency operation(window: ...), capability requirements, typed state lanes, and the outer outcome classes. Illustrative or deferred: payload fault variants, query/command service members, caller_key/provider_key idempotency, and outcome query.