# 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](/one/authoring/product) teaches how to declare an operation
and [Services and APIs](/one/guides/services) 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](/one/authoring/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](/one/reference/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](/one/platform/authority).

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](/one/model/composition) and
[providers and adapters](/one/platform/providers).

## 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](/one/examples/failure-handling)
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](/one/model/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](/one/lifecycle/change).

## 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`](https://github.com/muijf/one/tree/main/systems/system/idl/examples/hello/one).
- ParcelHub's Get/Place/Cancel operations, domain faults, idempotency, and typed
  state lanes:
  [`examples/parcelhub/one/contracts.one`](https://github.com/muijf/one/blob/main/systems/system/idl/examples/parcelhub/one/contracts.one).
- Support Triage's operations, workflow, and bounds:
  [`examples/support/triage/agent/one/support-triage.one`](https://github.com/muijf/one/blob/main/systems/system/idl/examples/support/triage/agent/one/support-triage.one).
- Order Review's Product `service` with an `operation` member:
  [`examples/order/review/web/one/contracts.one`](https://github.com/muijf/one/blob/main/systems/system/idl/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.

- [Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md)
- [Components](https://github.com/muijf/one/blob/main/systems/components/AGENTS.md)

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`.