Workflow-engine domain model

The engine separates a reusable execution graph from one run of that graph. Definitions describe possible work; scans and tasks record actual work.

Workflow family and version

A workflow family is the stable identity shared by related workflow definitions. A workflow definition is one executable version in that family: its steps, dependency graph, declared inputs, routing, deadlines, target cap, result schema, and content hash.

Two authoring paths have different version behavior:

• document publishing and repository synchronization create a new content-addressed version when the content changes; and
• interactive editor changes update the selected version in place.

The newest version is the current family member shown in workflow lists. Older published versions remain addressable.

A workflow-level parameter declaration defines a visible value a scan may bind into SQL and commands. Secret values are not workflow inputs at launch; each step instead names the current global secrets it requires at dispatch.

Workflow step

A workflow step describes one command shape and how tasks for that command are created. It owns:

• a command template and variables;
• references to workflow parameters and required global-secret names;
• input configuration, including optional read-only SQL;
• output handling and an optional writable output table;
• worker routing tags and provisioning hints;
• a per-step concurrency cap and timeout; and
• incoming dependency edges.

A step is not one execution. Depending on input expansion and Single dependencies, one step may produce many tasks.

Scan

A scan is one run of a workflow definition. It records the selected definition, resolved parameter values, lifecycle status, start and completion times, optional launch controls, and its tasks.

Recon-oriented scans additionally persist the expected target manifest and immutable launch identity used to correlate, cancel, and freeze a complete result set.

Scan task

A scan task is one dispatchable unit of work for one step in one scan. Its lifecycle is:

                       ┌──▶ Completed
Pending ──▶ Published ─┼──▶ Running ──┼──▶ Failed
   ▲                   │              └──▶ Stopped
   └──── recovery ─────┴──────────────┘

Normal execution moves through Published and Running before a terminal state. Recovery may reset an orphaned Published or Running task to Pending for redispatch.

The task stores its resolved variables, command value, routing tag, dispatch attempt, worker, timestamps, result path, error, and accepted result digest. For derived work it also stores:

• ParentTaskId — the immediate upstream task or expansion parent; and
• LineageId — the original input lineage shared by all descendant tasks.

See Dependencies and data flow for how those two identifiers make fan-out traceable and repeatable.

Workflow snapshot

At scan creation, Sonar stores a workflow snapshot with the workflow name and a copy of the steps needed to render the historical graph.

Relationship map

WorkflowFamily ──< WorkflowDefinition ──< WorkflowStep
                            │                    │
                            │                    └──< StepDependency
                            │
                            └──< Scan ──< ScanTask
                                  │          │
                                  │          ├── ParentTaskId ──▶ ScanTask
                                  │          └── LineageId
                                  │
                                  └── WorkflowSnapshot  (history and rendering)