Workflow

General rules

What makes a workflow graph valid — the shape a definition must have before it can run.

A definition is checked when you save it and again when a run starts. These are the rules a graph must satisfy. Get them right and a run just works; break one and Onepin rejects the graph with a message pointing at what to fix.

Every workflow needs three things

At minimum: one Source, one Generator, and one Export. The smallest working graph is Script → Generator → Export.

Script ──▶ Generator ──▶ Export
(source)   (operator)     (sink)

Export needs audio, and only the Generator produces it — so a Generator is required in every runnable workflow. A graph with no source or no export won’t run.

Nodes connect through compatible ports

Lines flow along edges from an output port to an input port. A port only accepts a line that already carries what the next node needs — Onepin compares what the upstream port provides against what the downstream port requires, and rejects a connection that would arrive missing data.

You don’t track this by hand: the canvas only lets you draw connections that fit, and a hand-authored definition is checked on save. A translator, for example, can’t feed Export directly — Export needs audio, which only the Generator adds in between.

Every node must be connected

An orphaned node — one nothing flows into or out of — fails validation. If a node is on the canvas, wire it in or remove it.

Validators route pass and fail

A validator has two outputs. Its pass output must reach Export, or lines that cleared the check would be silently dropped. Its fail output is optional: wire it back to the Generator to retry, or leave it unwired to drop failing lines. pass and fail can’t feed the same downstream port.

Loops are only for retries

The one legal cycle is a validator’s fail wired back to the Generator — the retry loop. Any other loop is rejected.

        ┌───────────────── fail ─────────────────┐
        ▼                                         │
   Generator ──▶ Accuracy validator ──▶ pass ──▶ Export

Saved isn’t the same as runnable

Save-time checks are lenient so you can keep a draft — for example, a cloned template with an empty script saves fine. Run-start is stricter: running a workflow whose required configs are empty fails with 422. Fix the flagged nodes and run again.