# Attractor

Attractor is a local-first workflow engine for running versioned graph workflows for AI software work.

## Language

**Workflow Launch**:
The act of starting a workflow run from a host-controlled entry point. A launch first produces an addressable run; waiting for completion is a host behavior layered on top.
_Avoid_: Fire-and-forget execution, job submission

**Host**:
The program or interface that starts and supervises workflow runs for a user. The bundled CLI is one host; external orchestrators, TUIs, and editor integrations are also hosts.
_Avoid_: Client, frontend, launcher

**Launch Request**:
The complete set of choices a host provides to start a workflow run. It identifies the workflow artifact and supplies launch-time inputs such as arguments, copied files, and the base ref.
_Avoid_: Options bag, job spec, invocation

**Workflow Artifact**:
The versioned graph definition a host launches. It is the source artifact for a run, even though the run records its own snapshot after launch.
_Avoid_: Config file, script, job template

**Launch Receipt**:
The stable, non-derivable information produced when a launch becomes a run. For now, the run identity is the receipt; other launch details should be obtained through stable inspection.
_Avoid_: Response payload, job ticket

**Launch Preflight**:
The checks a host performs before a launch becomes a run. Preflight verifies that the launch request is executable and representative of the intended source state; failures are launch rejections, not failed runs.
_Avoid_: Startup checks, validation phase

**Clean Source Worktree**:
A source worktree with no staged changes, unstaged tracked changes, or untracked non-ignored files. Launch requires a clean source worktree so the run starts from the same source state the user sees.
_Avoid_: Mostly clean checkout

**Source Worktree**:
The user's working tree from which a host launches a workflow. It is distinct from the run worktree created for the run.
_Avoid_: Original checkout, caller directory

**Launch Rejection**:
A failed attempt to launch before a run exists. A launch rejection produces no run identity, no run state, and no worktree.
_Avoid_: Failed run, aborted run

**Relaunch**:
The act of creating a new run from a previous launch intent. Relaunch is distinct from resume because it creates a new run identity rather than continuing an existing run.
_Avoid_: Retry, restart

**Resume**:
The act of continuing an existing run from its recorded state. Resume uses the workflow snapshot stored with that run, not the current workflow artifact path.
_Avoid_: Retry, relaunch

**Run**:
One execution trajectory of a workflow. A run has its own identity, local state, and lifecycle independent of the workflow file that defined it.
_Avoid_: Job, task, execution

## Example dialogue

Dev: "When we launch this workflow, do we just wait for it to finish?"

Domain expert: "No. A workflow launch should create an addressable run first, then the host may wait, inspect, cancel, resume, or answer gates as needed."

Dev: "So the CLI is the launcher?"

Domain expert: "The CLI is a host. It exposes launch to humans and scripts, but it should follow the same run lifecycle as any other host."