# Workflows and effects

One uses declarative workflows for durable coordination and explicit
implementation contracts for domain computation.

## Declarative workflow graphs

The canonical durable workflow is a bounded System IDL command/state graph. It
contains named states, terminal states, operation and activity invocations,
typed outcomes, timers, signals, compensation regions, approvals, seals, and
transitions.

The graph is inspectable and versionable. It is not a hidden general-purpose
programming language.

## Programmatic descent

When a workflow cannot be represented honestly as a graph, an application can
select a programmatic workflow implementation in native One, Rust, or another
admitted profile.

The workflow contract still owns inputs, outputs, domain faults, activities,
effects, history compatibility, and implementation identity. The program uses
a restricted deterministic API and carries an exact executable revision and
replay obligations.

## Effects are more than retry labels

Effects distinguish:

- pure, read-only, reversible, compensatable, and irreversible behavior;
- intent, dispatch, confirmation, and outcome unknown;
- idempotency and deduplication scope;
- compensation and irreversibility points;
- reconciliation after uncertain external results.

Before dispatching a non-pure effect, One records an exact intent. If the
external result is unknown, reconciliation occurs before unsafe repetition.

## Compensation is forward work

A compensation is a new effect with its own authorization, failure, receipt,
and evidence. It cannot erase that data was disclosed, an email was read, money
moved, or a physical action occurred.

A rollback is likewise a new forward transition, not time travel.

## Cancellation is not rollback

Dropping a future or cancelling a task does not prove an effect was not
dispatched. Activities and calls state cancellation, deadline, retry, delivery,
and unknown-outcome behavior explicitly.

Canonical owners:
[Authority](https://github.com/muijf/one/blob/main/systems/authority/AGENTS.md),
[Execution](https://github.com/muijf/one/blob/main/systems/execution/AGENTS.md),
[Components](https://github.com/muijf/one/blob/main/systems/components/AGENTS.md),
and
[History](https://github.com/muijf/one/blob/main/systems/history/AGENTS.md).