Workflow runtime

The runtime is a control loop around durable scan state. PostgreSQL is the source of truth; RabbitMQ carries dispatch messages; workers execute commands; MinIO carries file input and raw output.

End-to-end flow

PostgreSQL scan state
        │
        ▼
Reconciler computes ready tasks and capacity
        │ task state + outbox row, atomically
        ▼
Outbox publisher ──▶ RabbitMQ tag queue
                           │
                           ▼
                    matching worker
                           │
                  download inputs / run command
                           │
                           ├──▶ MinIO raw output
                           │
                           ▼
                 authenticated result callback
                           │
                  durable finalization work
                           │
                           ▼
                 parse and upsert Inventory

Reconciler

The reconciler periodically reloads each running scan and its live workflow definition. For one scan it:

1. builds the execution plan and current step states;
2. finds ready root, All, and Single work;
3. creates missing tasks;
4. places pending tasks within routing and concurrency budgets;
5. recovers stale in-flight work; and
6. marks the scan terminal only after tasks and result finalization are settled.

It derives the next action from persisted state rather than an in-memory cursor. A backend restart therefore resumes from the database on a later tick.

Task queue and routing

A step declares an OR-set of target tags. The dispatcher chooses one currently serviceable tag, records it on the task, and publishes to that tag's RabbitMQ routing key. A worker consumes the queues for the tags it advertises; execution location and worker image remain provisioning hints, while tags are the runtime placement contract.

The database transition to Published and the intent to publish are committed together through the transactional outbox. See Consistency for that boundary.

Worker runtime

A worker may run on any supported location as long as it can reach Sonar, RabbitMQ, and MinIO and advertises a matching tag. The same worker runtime:

1. pulses Sonar with its name, location, image, and tags;
2. pulls one job at a time from a routed queue;
3. checks whether the task should still run;
4. reports the Published → Running transition;
5. downloads referenced input files or directories;
6. resolves local paths, injects required secrets as process environment variables, and executes the command;
7. uploads declared output files or directories to MinIO;
8. reports the result through a per-dispatch authenticated callback; and
9. acknowledges the queue message only after the backend gives a durable disposition.

Worker disk is temporary. Inputs and generated outputs are removed after a persisted or permanently rejected result; durable artifacts live in MinIO and durable state lives in PostgreSQL.

Result finalization

The result callback verifies the dispatch attempt, worker identity, output digest, and HMAC. In one transaction it accepts the terminal task state and enqueues durable finalization work, then returns to the worker quickly.

Background finalizers lease that work, read raw output from MinIO, parse the declared schema, and apply structured effects. Workflow output can then enter Inventory through its bulk-upsert boundary. A scan cannot finalize while current result work remains incomplete.