> ## 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 orchestration pattern built from Plays and durable
customer tables. It represents a business process whose records move between
states over time. It is not a separate runtime service with an automatically
enforced business-state model.

The orchestrator Play determines a record's current state, selects the
appropriate transition, and persists the result according to the workflow's
rules. The states, allowed moves, table layout, and conflict policy belong to
the authored workflow.

## Business state outlives an individual execution

Consider an account-review process with `new`, `researched`, `needs_review`,
and `ready` states. A research run can finish successfully while the account
still needs a person's approval. Conversely, an account can remain researched
while a later notification attempt fails.

The business state answers where the account is in the process. Run status
answers what happened during one attempt to advance or inspect it. Combining
them into one status hides either the pending business decision or the failed
execution.

```mermaid theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
stateDiagram-v2
  [*] --> New
  New --> Researched: Research accepted
  Researched --> NeedsReview: Ambiguous evidence
  Researched --> Ready: Acceptance rule met
  NeedsReview --> Ready: Approved
  Ready --> [*]
```

This is an illustrative business model. Deepline does not supply these state
names or assume that every account should follow this path.

## The orchestrator and transition Plays have different jobs

A transition Play performs a bounded transformation: research the account,
evaluate a rule, or prepare a proposed outcome. The orchestrator decides
whether that outcome permits a move and records the accepted transition.

Separating those roles keeps a useful transformation reusable. Research logic
can serve an Engine and a one-time request without also owning approval or
handoff policy. The orchestrator remains the place where allowed moves are
visible.

`ctx.runPlay` composes compatible scalar children inline. A child that owns a
dataset, CSV, event wait, or explicit timeout has its own lifecycle and cannot
serve as that inline transition. A workflow that needs such work must arrange
it through top-level runs rather than assuming every Play can nest.

## Durable tables are the process's memory

The Engine pattern uses customer tables for state inputs and transition
outputs. An output record can connect the business key, accepted input, result,
previous and next states, and version identities. That history explains why an
account moved, not just what its current label says.

A run dataset is useful for inspecting an execution, but it is not a substitute
for the workflow's durable state contract. The table roles remain separate
even when the implementation joins them for a view.

The platform continues to own Play versions and run status. Customer-owned
state tables do not become an alternative source of truth for platform billing,
credentials, or Monitor configuration.

## A handoff is a data-integrity problem

Writing a transition output and supplying the next state's input are two
related facts. A process can fail between them. Recording only the final state
can hide a lost handoff; blindly retrying can create duplicate downstream work.

The Engine pattern therefore calls for deterministic transition and handoff
keys. The authored persistence logic uses those keys and database constraints
to recognize completed work and repair an incomplete handoff. Deepline does
not infer those business keys or implement a transaction across arbitrary
external systems.

Unknown states, forbidden moves, and invalid child results need explicit
handling in the orchestrator. A successful child run alone does not prove that
its proposed next state is allowed.

## Waiting changes the orchestration shape

Some processes can advance through several transitions in one invocation.
Others need an external event or human decision between transitions. Durable
state allows a later invocation to continue the business process without
keeping a conversation or one long execution open indefinitely.

The choice depends on the process's waiting boundaries. A terminal state means
this workflow has no next transition; it does not mean all possible future
work on the account is finished.

## Continue learning

* [Write Plays](https://deepline.com/docs/sdk-v2/plays.md#compose-an-engine-from-plays): implement and validate the Engine pattern.
* [Query Database](https://deepline.com/docs/database-access.md): access customer-owned state tables.
* [How Plays work](https://deepline.com/docs/plays/plays-overview.md): versions, runs, and replay boundaries.
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md): scalar composition and runtime methods.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.