# Core concepts

Amon Sul runs work under explicit, versioned policy and records what happened.
It is domain-agnostic: the integrating product supplies the meaning of its
entities, metadata, status codes, and rules. An invoice and a claim are examples
of caller-owned data, not built-in engine types.

## Definitions and execution context

| Concept           | Meaning                                                                                | Scope                    |
| ----------------- | -------------------------------------------------------------------------------------- | ------------------------ |
| Action            | One CALL, CHECK, CODE, or ODATA operation, with configuration and contracts            | Shared within the tenant |
| Sequence          | Ordered action references and mappings from caller inputs or prior outputs             | Shared within the tenant |
| Policy / matrix   | Sequences permitted at each status and routing for their exit conditions               | Shared within the tenant |
| Composite policy  | Several policy tracks, with role matrices and cross-track dependencies                 | Shared within the tenant |
| Published version | Immutable definition selected for execution                                            | Shared within the tenant |
| Entity type       | Caller-defined code used to register and bind entities                                 | Lane                     |
| Binding           | Assignment of an entity type to a published direct or composite policy                 | Lane                     |
| Entity            | Registered object with external identity, policy context, and current status or tracks | Lane                     |
| External system   | Connection code, target, and authentication used by outbound work                      | Lane                     |
| Run               | One admitted sequence execution, identified by a run UUID                              | Lane                     |

An action does work. A sequence connects that work. Policy interprets its facts.
Changing a policy does not require hiding a business status decision in action
code. The same published definitions can serve several lanes with different
entities, bindings, credentials, and targets. See [Lanes](https://docs.amonsul.io/concepts/lanes/).

## Execution, outcome, and routing

These are three separate questions:

| Layer     | Question                                                 | Evidence                                                    |
| --------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| Execution | Did the operation complete or error?                     | Technical execution evidence, including `is_system_failure` |
| Outcome   | What did it conclude?                                    | `exit_condition`, or candidate exit conditions              |
| Routing   | How did the configured policy interpret that conclusion? | Matched rule, severity, target status, or preserved status  |

A CHECK that finds missing data has completed its work. Its missing-data exit
condition is a business outcome. The matrix decides its severity and route.
Do not infer technical execution failure from an outcome's name or status colour.
The runtime retains some legacy severity fallbacks for other action types;
new policy should explicitly map the declared exit conditions.

## Actions and contracts

CALL sends HTTP work through Platform's integration proxy. ODATA builds an
OData request through the same boundary. Both select a stable `system_code` and
relative `path`; the run's lane supplies the actual connection. CHECK evaluates
configured rules. CODE runs saved JavaScript in a local QuickJS sandbox.

A sequence-start contract is JSON Schema describing the caller's input object.
Action input and output contracts describe the values each step consumes and
produces. A sequence's `input_mapping` connects those values. Duplicate output
variable names and missing references are publication problems. Use the
[JSON guide](https://docs.amonsul.io/developers/workflow-json/) and maintained contract examples
for exact syntax.

## Drafts, publication, and bindings

Drafts are editable. Published definitions are immutable; use a new version for
changes. Review the action and sequence versions referenced by a policy before
publishing its dependency tree. Publication validates the graph, contracts, and
outcome configuration.

Publication and activation for an entity are separate tasks. A lane's binding
chooses the policy for registration. Registration records the entity's policy
context, and sequence admission resolves against that context. Publishing a new
version alone does not prove that an existing entity now uses it.

Composite policies give an entity several tracks. A returned sequence identifies
its role and matrix version; dependency checks may make it unavailable and supply
a `blocked_reason`. Prefer that exact `sequence_id` when starting work.

## Evidence and delivery

Action Log records connect inputs, outputs, outcomes, policy rules, actor,
definition references, and execution time. Preserve the entity, lane, run UUID,
and action-reference UUID when investigating. Queue entries and live screens are
operational views; committed execution evidence is the recovery record.

Entity events feed webhook delivery and browser refresh. Browser realtime uses
the dashboard API's SSE stream. Finishing an execution, delivering its event,
and applying that event in another application are separate stages. See
[execution limits](https://docs.amonsul.io/guides/execution-limits/) and [common problems](https://docs.amonsul.io/guides/common-problems/).