/deepline-engine

name: deepline-engine
description: 'Build, publish, and verify a Deepline Play as a durable state machine over Customer DB tables, including a small paid pilot. Invoke this skill explicitly when the user asks to build an engine.'
disable-model-invocation: true

Deepline Engine

Quick Start

npm install -g deepline
deepline -h

CLI resolution

Run `deepline` when it is available. If the shell reports that command is missing, use `<workspace-root>/.deepline/runtime/bin/deepline` (or the npm-created `.cmd` shim on Windows). If neither exists, follow `https://code.deepline.com/INSTALL.md` to set up Deepline.

Build an engine from the state machine the user defines.

An engine is an orchestrator Deepline Play that accepts an input, determines its state, calls the transition Play for that state, and produces a new state. The durable data plane lives in Customer DB: every state has an input table and an output table. The output of one transition can become the input to the next state.

The user owns the states, transition rules, transformations, and terminal behavior. This skill owns the reusable structure for turning those decisions into a replay-safe Play. Infer routine names, schemas, advancement behavior, and implementation details from the request and repository conventions. Ask only when missing information would force the engine to invent substantive business policy or create an unsafe side effect. Do not import an outbound workflow, GTM recipes, provider choices, or domain-specific policy unless the user asks for them.

Core model

For each state, define:

| Part | Meaning | | --------------- | ----------------------------------------------------------------------------------- | | Input table | Rows waiting to be handled in this state | | State decision | The user-defined rule that establishes the row's current state | | Transition Play | The child Play that performs the transformation for this state | | Output table | The input, result, transition status, and next state | | Next input | The row admitted to the next state's input table, unless the transition is terminal |

Keep the state decision explicit. Inferring state from incidental fields creates transitions the user did not define and makes replay behavior hard to explain.

Workflow

1. **Capture the state machine.** Extract the states, initial state, terminal states, allowed transitions, state-decision rules, and transformation for each state from the request and available project context. Resolve routine omissions with explicit, reported assumptions. Ask only when competing interpretations would materially change business behavior. 2. **Define row identity.** Choose the stable business key and a transition idempotency key. A retry must address the same row and transition instead of creating a second result. 3. **Define the tables.** Give every state an input table and an output table in Customer DB. Infer clear names and domain columns from the state machine and repository conventions. Record the structural fields needed to connect an input, its result, and the next state. 4. **Choose a durable source directory.** Generate the engine under a maintained project directory inferred from repository conventions. Keep the orchestrator at the engine directory's top level and new child Plays in descriptive subfolders, alongside shared types, README, and Mermaid diagram as project source. Do not use an ignored `tmp/` scaffold; temporary paths hide work from version control and make the engine disposable. 5. **Resolve every transition Play before authoring one.** Search callable Plays visible to the user's workspace with `deepline search "<transition input -> transition outcome>" --type plays`. Inspect owned and prebuilt candidates with `deepline describe <name>`. Reuse an exact contract match; names are only hints, so verify input, output, and inline-composition compatibility. If no candidate fits, author one new Play for that transition instead of embedding its transformation in the orchestrator. 6. **Author the orchestrator Play.** Write a `.play.ts` file that default-exports an async function of its input (`import deepline from 'deepline'; export default async function (input: EngineInput) { ... return { ... }; }`; the file name is the default Play name, `export const config = { name }` overrides it). Determine the state, select the matching transition Play, and call it through `deepline.runPlay(...)` with a stable key. The orchestrator owns state routing and Customer DB persistence; transition Plays own transformations. 7. **Persist the transition.** Materialize the accepted input, the child Play result, `from_state`, `to_state`, status, error or miss information, timestamps, workflow version, transition Play identity/version, and idempotency key. If the transition continues, write the next state's input idempotently. 8. **Choose the advancement model.** Infer one transition per invocation or multiple transitions per invocation from the workflow. Default to multiple transitions through terminal completion when no external event must occur between states. Record the choice and its retry and observability implications instead of pausing for confirmation. 9. **Validate every edge.** Check every new transition Play and the orchestrator. Before the paid-pilot gate, use static checks and provider-free fixtures to test each allowed transition, each terminal state, an invalid or unknown state, a child Play failure, an invalid state returned by a child, and replay of a completed transition. Defer provider-executing edge tests for this new engine to its bounded authoring pilot after caps and workspace authorization are verified. A separate post-fix acceptance follows [references/post-fix-verificat