> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deepline Engines

> How an orchestrator Play moves records through durable states with transition Plays and Customer DB tables.

An **Engine** is an orchestrator Play for a user-defined state machine. It
determines a record's current state, calls the transition Play for that state,
persists the outcome, and admits the record to the next state when allowed.
States and transition rules come from your process. Deepline does not impose a
fixed set of states.

## Engine parts

| Part | Responsibility |
| - | - |
| Orchestrator Play | Determines the current state, selects a transition Play, and persists the transition. |
| Transition Play | Transforms one record for a defined state and returns its result and proposed next state. |
| State input table | Holds the record and a stable key for the current state. |
| State output table | Holds the accepted input, result, status, next state, version, and transition key. |
| Next-state input table | Receives the record after a valid nonterminal transition. |

Each state has distinct input and output table roles in Customer DB. A
run-scoped Runtime Sheet from `ctx.dataset()` cannot replace these durable
tables. Customer DB stores workflow records; Deepline stores Play versions,
platform run status, credentials, and billing state in its own systems.

## A record's path

For example, an account review Engine might define `new`, `researched`,
`needs_review`, and `ready`. The team defines which transitions are allowed.
The following path is illustrative:

```text theme={null}
new → researched → ready
           ↓
      needs_review
```

When a `new` account enters the Engine, the orchestrator selects a research
Play. The research Play returns its result and a proposed next state. The
orchestrator checks that the move is allowed, writes the output row, and writes
the next input row. A terminal state such as `ready` has no next-state handoff.

The Engine can run one transition per invocation when it must wait for an
external event. It can also continue through several transitions in one
invocation when no external event is required. The chosen model must be clear
in the Engine's contract.

## Transition record

The output table preserves enough information to explain and retry a move:

* A stable business key and a reference to the accepted input.
* The previous state, proposed next state, result, and transition status.
* A typed error or miss reason for failed and invalid transitions.
* The processed time, workflow version, and transition Play identity and version.
* A deterministic transition idempotency key.

The same transition key identifies a retry. A retry can repair a missing
next-state input without duplicating a completed output. Unknown states and
forbidden next states produce a recorded invalid result and a failure. A child
Play failure produces a recorded failed result and no handoff.

## Play composition and validation

The orchestrator calls a compatible transition Play through `ctx.runPlay`.
Before creating a child Play, inspect workspace Plays and prebuilts for a
matching input and output contract. A child Play that owns a dataset, CSV,
event wait, or another lifecycle boundary cannot run as an inline transition.

Check the orchestrator and each new child Play before publication. Validate
allowed moves, terminal states, unknown states, child failures, invalid child
results, and replay. A small pilot with synthetic records then checks the
published versions and actual state changes. Provider-backed pilots need
explicit credit limits.

An Engine is a way to arrange [Plays](/docs/plays/plays-overview) and
[Customer DB tables](/docs/database-access). It is not a separate runtime service.
For a plain-language overview, read
[What is a Deepline Engine?](https://deepline.com/blog/what-is-a-deepline-engine).