@xeplr/workflow-engine 1.0.1 → 3.0.0

package/README.md

@@ -28,7 +28,7 @@ The shared `@xeplr/*` libraries (`actions`, `db`, `expression-handler`, `schema-
 
 | Export | Purpose |
 |---|---|
-| `startEngine(config)` | Connect workflow's database (creating it if missing), run its migrations, ready `xeplr_configs`, register the action catalog. Idempotent. `config.db` is required; throws if no application id is registered. Config: `db` (`{ name, connection, connectionName?, mts?, migrationsTable? }`), `applicationId`, `tenantTables`, `migrations`, `migrate` (`false`: connect without migrating — a second process of an install whose API migrates), `startJob` (below) |
+| `startEngine(config)` | Connect workflow's database (creating it if missing), run its migrations, ready `xeplr_configs`, register the action catalog. Idempotent. `config.db` is required; throws if no application id is registered. Config: `db` (`{ name, connection, connectionName?, mts?, migrationsTable? }`), `applicationId`, `tenantTables`, `migrations`, `migrate` (`false`: connect without migrating — a second process of an install whose API migrates), `startJob` (below), `schedule` (`false`: no schedule tick in this process), `scheduleIntervalMs` (default 30000) |
 | `resumeByKey(key, output?, opts?)` | Server-side, in-process resume of a run parked on a `wait` step. `opts.status: 'failed'` resolves the step as failed. Throws `err.code` `RESUME_KEY_INVALID` (used/unknown, normal for host routes) or `RESUME_KEY_NOT_READY` (step still running; nothing consumed, retry) |
 | `embedRequiredEnv` | `['DB_WORKFLOW']`, spread into a host's `env.required.js` |
 | `callbackRequiredEnv` | `['WORKFLOW_PUBLIC_URL']`, only for hosts using steps that call out (`job-run`) |
@@ -36,7 +36,9 @@ The shared `@xeplr/*` libraries (`actions`, `db`, `expression-handler`, `schema-
 | `db` | `connectDb`, with `.model(name)` bound to workflow's own connection |
 | `runner` | `lib/workflowRunner.js`: `startRun`, `resumeByKey`, `resolveParams`, `collectParams` |
 | `flows` | `lib/flows.js`: the flows facade (list, create, put, publish, start, submit, runs) and `touchesScreens` |
-| `jobChains` | `lib/jobChains.js`: a job's "After this job" rules as a workflow — `getChain`, `putChain`, `jobFinished`, `setJobStarter`, `touchesChains` ([Job chains](#job-chains-libjobchainsjs)) |
+| `triggers`, `registerTrigger` | `lib/triggers.js`: what starts a workflow — the registry of kinds, `validate`, `emit`, the schedule `tick`, `describe` ([Triggers](#triggers-libtriggersjs)) |
+| `conditions` | `lib/conditions.js`: `whenToCondition`, `compileTransitions` ([Conditions](#conditions-written-simply-libconditionsjs)) |
+| `jobs`, `jobFinished` | `lib/jobs.js`: jobs as steps and as triggers — `setJobStarter`, `jobFinished` ([Jobs](#jobs-as-steps-and-as-triggers-libjobsjs)) |
 | `actionCatalog`, `envExposed`, `xcfgSetup` | The action whitelist, the `WORKFLOW_ENV_EXPOSED` allowlist, the shared `xeplr_configs` attachment |
 
 The package reads `migrations/` and `migrations-tenants/` from disk (`"xeplr": { "readsFromDisk": [...] }` in `package.json`), so a build that compiles it must ship those folders beside it.
@@ -49,15 +51,18 @@ engine/
 ├─ lib/
 │  ├─ workflowRunner.js     startRun, resumeByKey, resolveParams, collectParams
 │  ├─ flows.js              the flows facade: screens as steps
-│  ├─ jobChains.js          a job's "After this job" rules, kept as a workflow
+│  ├─ triggers.js           what starts a workflow: manual, api, schedule, job, and more
+│  ├─ jobs.js               jobs as steps (job-run) and as triggers (jobFinished)
+│  ├─ conditions.js         an arrow's `when` compiled into its condition
 │  ├─ actionCatalog.js      whitelist of @xeplr/actions built-ins + local actions
-│  ├─ actions/              local actions: job-run, screen-show, job-chain-decide/-next
+│  ├─ actions/              local actions: job-run, decide, screen-show
 │  ├─ envExposed.js         WORKFLOW_ENV_EXPOSED allowlist for {env.*}
 │  └─ db.js                 connectDb + model(name) bound to workflow's own connection
 ├─ db/xcfgSetup.js          shared @xeplr/actions attachConfig({ service: 'xeplr-workflow' })
 ├─ models/                  Company, Workspace, Workflow, WorkflowStep, WorkflowRun,
-│                           WorkflowStepRun, WorkflowResumeKey, WorkflowRunEdge
-├─ migrations/              0003–0014, workflow's own tables
+│                           WorkflowStepRun, WorkflowResumeKey, WorkflowRunEdge,
+│                           WorkflowTriggerState
+├─ migrations/              0003–0015, workflow's own tables
 ├─ migrations-tenants/      0001–0002: standalone workflow's companies / workspaces
 └─ test/                    run.mjs + *.test.mjs
 ```
@@ -125,43 +130,100 @@ host gives workflow is the boundary.
 Not read by the runner: `workflows.status`, `workflows.kind`,
 `workflow_steps.layout`, `workflow_steps.sampleOutput`, `workflow_steps.timeoutMs`.
 
-## Job chains (`lib/jobChains.js`)
+## Triggers (`lib/triggers.js`)
 
-**Every hand-off between jobs goes through this engine.** `@xeplr/jobs` never
-starts another job; a job's screen keeps a list of "After this job" rules, and
-`putChain(jobId, { rules, jobName })` turns them into one hidden workflow,
-kind `job-chain`, key `job-chain-<jobId>`:
+**What starts a workflow is its `trigger`**, one shape per kind, and the engine acts on it. Every kind goes through one registry, the way every step goes through the action registry:
 
-- `decide` (`job-chain-decide`, does nothing): its transitions are the rules, first match wins, and no match ends the run successfully;
-- `run_1 … run_n` (`job-chain-next`, wait steps): start that rule's job and park until it reports back.
+| kind | settings | fires |
+|---|---|---|
+| `manual` | — | someone presses Start (nothing to arm) |
+| `api` | — | another system calls the run (nothing to arm) |
+| `schedule` | `cron` (`"0 9 * * 1"`), `timezone?` | when the cron expression is due |
+| `job` | `jobId`, `when`: `success` (default) \| `failed` \| `finished` | when that job finishes that way |
+
+Every kind also takes `enabled: false`, which switches it off without losing it.
+
+The same rules hold for every kind:
+
+- **Only a published workflow fires.** A draft never does.
+- **It is checked when it is saved.** The `Workflow` model validates `trigger` on every insert and update; an unknown kind, a job trigger without `jobId` or a cron expression that cannot be read is a 400 naming the problem.
+- **A run gets what fired it.** It is stored as `workflow_runs.triggerData` and read by bindings and by the conditions on arrows as `{trigger.*}`: a job's `{trigger.status}`, `{trigger.window.from}`, `{trigger.output.totalRows}`; a schedule's `{trigger.dueAt}`. A run started by hand has `{trigger.kind}` only.
+- **What it did is a row.** `workflow_trigger_states` keeps the last fire and its run, the next due time, and the last skip and why: a required parameter nobody supplies, a workflow with no steps. A workflow that cannot start is recorded and never thrown at the job that finished. `describe(workflow)` answers `{ trigger, on, lastFiredAt, lastRunId, lastSkippedAt, lastSkipReason, nextDueAt }`.
+
+**The schedule tick.** `startEngine` runs it every 30 s, on a timer that does not keep the process alive (`schedule: false` turns it off in a process). It reads every tenant's timed triggers and starts each run in its own workflow's tenant context.
+- A trigger seen for the first time, or whose settings changed, is given its next due time and does **not** fire, so publishing never starts a run for a time already past.
+- A due trigger is **claimed** by a conditional update of its due time, so two processes running the tick start it once.
+
+**A host's own kinds.** `registerTrigger(kind, { validate, due?, matches? })`:
+- a time kind gives `due(trigger, from)`, its next due `Date`;
+- an event kind gives `matches(trigger, event)`, and the host calls `triggers.emit(kind, event)` when the event happens.
+
+Folder and mailbox watchers are next, as kinds of this registry.
+
+## Conditions written simply (`lib/conditions.js`)
+
+An arrow (a transition) can carry `when` instead of an engine `condition`. The engine compiles it into the `condition` every time the step is saved (`WorkflowStep`'s hooks) and keeps `when` beside it, so a screen reads back exactly what it wrote. `when` is one of:
 
-A rule is `{ when, run, inputs?, carry? }`:
+- `{ "field": "trigger.status", "op": "=", "value": "success" }`
+- `{ "all": [ … ] }` or `{ "any": [ … ] }`
+- empty, meaning "otherwise"
+
+The comparisons are the flows facade's: `=`, `!=`, `>`, `>=`, `<`, `<=`, `contains`, `notContains`, `startsWith`, `endsWith`, `in`, `notIn`, `between`, `isEmpty`, `isNotEmpty`.
+
+A bad `when` is refused when it is saved, naming the step and the arrow. That is how a screen of your own (and the jobs screen's "After this job") writes branches without knowing the node format.
+
+## Jobs as steps and as triggers (`lib/jobs.js`)
+
+A job meets a workflow in two places, and both are ordinary workflows:
+
+- **As a step:** `job-run` starts a job and parks (a `wait` step) until it reports back. The run carries on with its result.
+- **As a trigger:** `{ "kind": "job", "jobId": "…", "when": "success" }` starts the workflow when that job finishes.
+
+Branch on how a job ended with a `decide` step: it does nothing itself, and the conditions on its arrows read `{trigger.*}`.
 
 ```json
-[
-  { "when": { "field": "output.totalRows", "op": ">", "value": 0 }, "run": "<jobId>",
-    "inputs": { "region": "{output.region}" }, "carry": { "rows": "{output.totalRows}" } },
-  { "when": { "all": [ { "field": "status", "op": "=", "value": "failed" } ] }, "run": "<jobId>" },
-  { "run": "<jobId>" }
-]
+{ "name": "After the nightly load", "status": "published",
+  "trigger": { "kind": "job", "jobId": "<load>", "when": "finished" },
+  "steps": [
+    { "stepKey": "decide", "actionName": "decide", "transitions": [
+        { "when": { "field": "trigger.status", "op": "=", "value": "success" }, "target": "report" },
+        { "when": null, "target": "alert" } ] },
+    { "stepKey": "report", "actionName": "job-run", "kind": "wait",
+      "values": { "jobId": "<report job>", "callbackUrl": "{resumeUrl}" } },
+    { "stepKey": "alert", "actionName": "send-email", "values": { "to": "ops@example.com", "subject": "Load failed: {trigger.error.message}" } }
+  ] }
 ```
 
-- **`when`** is `{ field, op, value }`, `{ all: [...] }`, `{ any: [...] }`, or empty for "otherwise" (last only). Fields start with `status` (`success`/`failed`), `output.` (what the finished job's action returned), `window.`, `carry.`, `error.` or `jobId`. The comparisons are the flows facade's (`flows.comparisonNode`), so `=` means one thing everywhere.
-- **The period flows on.** The next job is started with the finished job's `window` unless the rule's `inputs` set one, so a chain covers one period from its first job to its last.
-- **`inputs`** fill inputs of the next job — only `window` and the names that job lists in `acceptsInputs` (`@xeplr/jobs` refuses the rest, and the run fails saying which).
-- **`carry`** adds values for later jobs, read as `carry.<name>`. Bindings like `{output.x}` keep their type when they are the whole value.
-- **Loops stop**: a job that has already run in this chain, or a chain 25 jobs long, fails the step with a message.
+**A finished job gives the workflow it triggers** `{trigger.*}`:
+- `jobId` and `status` (`success` / `failed`)
+- `error`, when it failed
+- `output`: what its action returned
+- `window`: the period it ran for. That is the range it was given or, given none, the range its action reports it covered.
+- `given` / `used`: those two ranges separately
+- `carry`: values carried from the jobs before it
+- `path`: the jobs that led here
 
-`putChain` with an empty list sets the workflow back to draft (its runs stay). `getChain` answers the rules as written (kept on the `decide` step). A `job-chain` workflow cannot be saved through `/workflows/save` (`touchesChains`), like a screens flow.
+**When a job started such a run, `job-run` carries it on:**
+- **The period flows.** The next job gets the finished job's `window` unless the step's `inputs` set one, so a chain of workflows covers one period from its first job to its last.
+- **The next job is offered both earlier ranges**, as `@xeplr/jobs`' `previous.given` / `previous.used`.
+- **`carry`** (a `job-run` input) adds values for the jobs after it.
+- **Loops stop.** A job already on the path, or a path 25 jobs long, fails the step with a message.
+
+The next job takes only `window` and the inputs it lists in `acceptsInputs`; `@xeplr/jobs` refuses the rest, naming them.
 
 **The host connects jobs, in-process.** The engine never imports jobs:
 
 ```js
 await engine.startEngine({ db, startJob: (jobId, body) => jobs.trigger(jobId, body) });
-await jobs.init({ /* … */ onFinish: (report) => engine.jobChains.jobFinished(report) });
+await jobs.init({ /* … */ onFinish: (report) => engine.jobFinished(report) });
 ```
 
-`jobFinished(report)` takes `@xeplr/jobs`' finish envelope. If the run was started by a chain step it resumes that step (retrying while the step parks), and if the finished job has rules it starts its chain with params `{ jobId, status, error, output, window, carry, path }`. With `startJob` set, the canvas's `job-run` step starts jobs the same way, with no `jobsUrl` and no HTTP call.
+`jobFinished(report)` takes `@xeplr/jobs`' finish envelope. It resumes the `job-run` step that started the job (retrying while that step parks) and starts every workflow the job triggers. Without `startJob`, `job-run` starts jobs over HTTP (`jobsUrl`, and `WORKFLOW_PUBLIC_URL` for the callback).
+
+**Job chains are gone.** Migration 0015 converted each "After this job" chain (kind `job-chain`) into an ordinary workflow:
+- it gets a `job` trigger (`when: finished`);
+- its `decide` and `job-run` steps keep the same behaviour;
+- conditions and bindings now read `trigger.*`.
 
 ## Tests
 
@@ -169,12 +231,21 @@ await jobs.init({ /* … */ onFinish: (report) => engine.jobChains.jobFinished(r
 npm test          # node test/run.mjs — each *.test.mjs in its own process
 ```
 
-No database or network needed, except `jobChains.test.mjs`, which runs on a real Postgres when `WORKFLOW_TEST_PG='{"host":…,"port":…,"user":…,"password":…}'` is set (scratch databases, created and dropped) and is skipped otherwise. CI and the release start a throwaway Postgres and set it, so neither ships on a skipped suite. `npm install` first: the peers install with it.
+No database or network needed, except `triggers.test.mjs`, which runs on a real Postgres when `WORKFLOW_TEST_PG='{"host":…,"port":…,"user":…,"password":…}'` is set (scratch databases, created and dropped) and is skipped otherwise. CI and the release start a throwaway Postgres and set it, so neither ships on a skipped suite. `npm install` first: the peers install with it.
 
 | Suite | Covers |
 |---|---|
-| `jobChains.test.mjs` | "After this job" with the real `@xeplr/jobs` (a dev dependency) wired as a host wires it: rules ⇄ workflow, every refusal, A → B → D with A's period and carried values, otherwise, no match, a failed job followed, loops and over-long chains stopped, an input the next job does not accept, `job-run` in-process, rules removed |
-| `actionCatalog.test.mjs` | Ready vs placeholder detection; registered names are kebab-case; `spawnProgram` not offered |
+| `conditions.test.mjs` | `when` → condition: a comparison, otherwise, nested all/any, every refusal naming the step and arrow, `when` kept beside the compiled condition |
+| `triggers.test.mjs` | Triggers with the real `@xeplr/jobs`, wired as a host wires it:
+- every refusal when saved
+- a job finishing starts the workflows it triggers, B and D running with A's period
+- `success`, `failed` and `finished`
+- a trigger switched off, and a draft, never firing
+- a loop stopped
+- a workflow that cannot start, recorded as a skip
+- the schedule's first sight, its due time, two ticks starting it once, a changed cron
+- migration 0015 turning an old job chain into a workflow that runs |
+| `actionCatalog.test.mjs` | Ready vs placeholder detection; registered names are kebab-case; `spawnProgram` not offered; `decide` and `job-run` offered |
 | `envExposed.test.mjs` | Nothing exposed by default; exact, case-sensitive matching; globs fail closed (against real `interpolateAll`) |
 | `requires.test.mjs` | Every relative `require` in this package points at a file (Node only notices a missing one when the line runs; a bundler refuses it up front) |
 | `paths.test.mjs` | `MIGRATIONS_DIR` and `TENANT_MIGRATIONS_DIR` exist inside the package, hold SQL, and are listed in `readsFromDisk` (an undefined one makes the migrator run the HOST's `./migrations` against workflow's database) |

package/index.js

@@ -6,7 +6,8 @@ var actionCatalog = require('./lib/actionCatalog');
 var envExposed = require('./lib/envExposed');
 var workflowRunner = require('./lib/workflowRunner');
 var flows = require('./lib/flows');
-var jobChains = require('./lib/jobChains');
+var jobs = require('./lib/jobs');
+var triggers = require('./lib/triggers');
 var xcfgSetup = require('./db/xcfgSetup');
 
 // THE WORKFLOW ENGINE — everything that runs a workflow, with no HTTP in it:
@@ -39,12 +40,15 @@ var TENANT_MIGRATIONS_DIR = path.join(__dirname, 'migrations-tenants');
  * @param {Function} [config.startJob] - async (jobId, { inputs, chain,
  *   callbackUrl }) → { occurrenceId }: how this host starts a job. With
  *   @xeplr/jobs in the same process, `(id, body) => jobs.trigger(id, body)`.
- *   Used by "After this job" chains and by the job-run step. Unset, those
- *   steps fail and say so (job-run falls back to its jobsUrl over HTTP).
+ *   Used by the job-run step; unset, it falls back to its jobsUrl over HTTP.
+ * @param {boolean} [config.schedule=true] - false: do not run the schedule
+ *   tick in this process (lib/triggers.js). Two processes may both run it —
+ *   a due trigger is claimed, so it starts once — but one is enough.
+ * @param {number} [config.scheduleIntervalMs=30000] - how often it looks.
  */
 async function startEngine(config) {
   config = config || {};
-  if (config.startJob !== undefined) jobChains.setJobStarter(config.startJob);
+  if (config.startJob !== undefined) jobs.setJobStarter(config.startJob);
   if (!config.db) {
     throw new Error('startEngine: config.db is required — workflow owns its own domain data regardless of how it is mounted');
   }
@@ -179,6 +183,9 @@ async function startEngine(config) {
   // secret is only catchable if it is visible somewhere.
   envExposed.logExposure();
 
+  // Scheduled workflows start themselves from here on. The timer does not
+  // keep the process alive.
+  if (config.schedule !== false) triggers.startTicking(config.scheduleIntervalMs);
 }
 
 // Env vars a HOST embedding workflow must supply — spread into the host's
@@ -284,7 +291,18 @@ module.exports = {
   envExposed: envExposed,
   runner: workflowRunner,
   flows: flows,
-  jobChains: jobChains,
+  // What starts a workflow: the registry of kinds (manual, api, schedule,
+  // job — and a host's own via registerTrigger), the schedule tick, and what
+  // a trigger last did.
+  triggers: triggers,
+  registerTrigger: triggers.registerTrigger,
+  // Jobs as steps and as triggers. A host with @xeplr/jobs passes jobs'
+  // onFinish to jobFinished, so a finished job starts the workflows it
+  // triggers and resumes the step that started it.
+  jobs: jobs,
+  jobFinished: jobs.jobFinished,
+  // An arrow's `when` ({ field, op, value }) → the engine's condition node.
+  conditions: require('./lib/conditions'),
   xcfgSetup: xcfgSetup,
   auth: require('./lib/auth')
 };

package/lib/actionCatalog.js

@@ -59,7 +59,9 @@ var WANTED = [
 // same way and appearing in the same catalog, so the step editor needs no
 // notion that some actions come from here and some from there.
 var LOCAL = [
-  require('./actions/jobRun')
+  require('./actions/jobRun'),
+  // A step that only branches: its arrows hold the conditions.
+  require('./actions/decide')
 ];
 
 // REGISTERED BUT NOT OFFERED.
@@ -76,11 +78,7 @@ var LOCAL = [
 // that facade knows how to show the screen or how to resume it. Hiding it is
 // not secrecy; it is not offering half of something.
 var HIDDEN = [
-  require('./actions/screenShow'),
-  // A job chain's two steps, generated by lib/jobChains.js from a job's
-  // "After this job" rules — same reasoning as screen-show.
-  require('./actions/jobChainSteps').decide,
-  require('./actions/jobChainSteps').next
+  require('./actions/screenShow')
 ];
 
 var HIDDEN_NAMES = HIDDEN.map(function(def) { return def.name; });

package/lib/actions/decide.js

@@ -0,0 +1,15 @@
+// decide — A STEP THAT ONLY CHOOSES WHERE TO GO.
+//
+// It does nothing itself; its arrows (transitions) carry the conditions, first
+// match wins, and a blank one is "otherwise". The way to branch on what
+// started the run ({trigger.status} after a job) or on anything earlier,
+// before any other step has run.
+module.exports = {
+  name: 'decide',
+  description: 'Choose the next step from conditions on its arrows — on what started the run, ' +
+               'or on anything earlier. Does nothing itself.',
+  requires: [],
+  inputSchema: [],
+  outputSchema: null,
+  execute: async function() { return {}; }
+};

package/lib/actions/jobRun.js

@@ -1,6 +1,6 @@
 // job-run — START A JOB AND PARK UNTIL IT REPORTS BACK.
 //
-// The step behind an arrow on the "connect jobs" canvas. Everything it does is
+// A job as a STEP of any workflow (a job as a TRIGGER is lib/triggers.js). Everything it does is
 // two HTTP calls' worth of glue between two products that do not import each
 // other:
 //
@@ -56,7 +56,10 @@ module.exports = {
     { name: 'inputs', type: 'object', order: 4, group: 'Advanced',
       description: 'Values to override the job\'s saved inputs, for this run only. The job row ' +
                    'is not changed. Commonly a window: { window: { from, to } }.' },
-    { name: 'timeoutMs', type: 'number', default: 30000, order: 5, group: 'Advanced',
+    { name: 'carry', type: 'object', order: 5, group: 'Advanced',
+      description: 'Values carried along to the jobs after this one — a workflow those jobs trigger ' +
+                   'reads them as {trigger.carry.*}.' },
+    { name: 'timeoutMs', type: 'number', default: 30000, order: 6, group: 'Advanced',
       description: 'How long to wait for the TRIGGER call to be accepted. Nothing to do with ' +
                    'how long the job itself may run — that is the job\'s own timeout.' }
   ],
@@ -69,12 +72,19 @@ module.exports = {
     // jobsUrl and no credentials: the call runs inside this run's tenant
     // context, which is the job's. Without it this step falls back to the
     // jobs API over HTTP below.
-    var startJob = require('../jobChains').jobStarter();
+    var jobs = require('../jobs');
+    // WHEN THIS RUN WAS STARTED BY A JOB FINISHING, the period flows on to
+    // this job unless the step sets one, carried values and the path travel
+    // with it, and a job already on the path is refused as a loop
+    // (jobs.nextJobCall). Any other run passes the step's inputs as they are.
+    var call = jobs.nextJobCall(ctx.system && ctx.system.trigger, input.jobId, input.inputs, input.carry);
+    var startJob = jobs.jobStarter();
     if (startJob) {
+      call.chain.resumeKey = (ctx.system && ctx.system.resumeKey) || null;
       var started = await startJob(input.jobId, {
-        inputs: input.inputs || null,
+        inputs: Object.keys(call.inputs).length ? call.inputs : null,
         callbackUrl: input.callbackUrl || null,
-        chain: { resumeKey: (ctx.system && ctx.system.resumeKey) || null }
+        chain: call.chain
       });
       return {
         jobId: input.jobId,
@@ -125,8 +135,9 @@ module.exports = {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          inputs: input.inputs || undefined,
-          callbackUrl: input.callbackUrl
+          inputs: Object.keys(call.inputs).length ? call.inputs : undefined,
+          callbackUrl: input.callbackUrl,
+          chain: call.chain
         }),
         signal: controller.signal
       });

package/lib/conditions.js

@@ -0,0 +1,72 @@
+// AN ARROW'S CONDITION, WRITTEN SIMPLY.
+//
+// The engine evaluates conditions as nodes — { left: { field }, op: 'eq',
+// right: { value } }. A screen of anyone's (the jobs screen's "After this
+// job", an app built on this API) can instead write an arrow's `when`:
+//
+//   { "field": "trigger.status", "op": "=", "value": "success" }
+//   { "all": [ … ] }   { "any": [ … ] }   null — "otherwise"
+//
+// and the engine compiles it into `condition` when the step is saved
+// (models/WorkflowStep.js), keeping `when` beside it so a screen reads back
+// exactly what it wrote. One compiler, here — the comparisons are the flows
+// facade's (flows.comparisonNode), so `=` means one thing everywhere.
+var flows = require('./flows');
+
+var FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_-]+)*$/;
+
+function invalid(message) {
+  var err = flows.fail(400, 'CONDITION_INVALID', message);
+  // A model validation error by name, so the generic save answers it as one.
+  err.name = 'ValidationError';
+  err.type = 'ModelValidation';
+  err.statusCode = 400;
+  err.data = { transitions: [{ message: message, keyword: 'when' }] };
+  return err;
+}
+
+/** `when` → the engine's condition node; null/undefined → null ("otherwise"). */
+function whenToCondition(when, where) {
+  where = where || 'This condition';
+  if (when === null || when === undefined) return null;
+  if (typeof when !== 'object' || Array.isArray(when)) {
+    throw invalid(where + ': the condition must be an object such as ' +
+      '{ "field": "trigger.status", "op": "=", "value": "success" }, or empty for "otherwise".');
+  }
+  if (when.all !== undefined || when.any !== undefined) {
+    var key = when.all !== undefined ? 'all' : 'any';
+    var list = when[key];
+    if (!Array.isArray(list) || !list.length) throw invalid(where + ': `' + key + '` needs a non-empty list of conditions.');
+    var group = {};
+    group[key] = list.map(function(c, i) {
+      var node = whenToCondition(c, where + ', ' + key + ' ' + (i + 1));
+      if (!node) throw invalid(where + ': an empty condition inside `' + key + '`.');
+      return node;
+    });
+    return group;
+  }
+  var field = String(when.field == null ? '' : when.field).trim();
+  if (!field) throw invalid(where + ': `field` is required — e.g. "trigger.status" or "output.rowsMoved".');
+  if (!FIELD_PATTERN.test(field)) throw invalid(where + ': "' + field + '" is not a usable field.');
+  try {
+    return flows.comparisonNode(when, where, field, 'CONDITION_INVALID');
+  } catch (err) {
+    throw invalid(err.message);
+  }
+}
+
+/**
+ * A step's transitions with every `when` compiled into its `condition`.
+ * Transitions without `when` are left exactly as they are.
+ */
+function compileTransitions(transitions, stepName) {
+  if (!Array.isArray(transitions)) return transitions;
+  return transitions.map(function(t, i) {
+    if (!t || typeof t !== 'object' || t.when === undefined) return t;
+    var out = Object.assign({}, t);
+    out.condition = whenToCondition(t.when, (stepName ? 'Step "' + stepName + '"' : 'A step') + ', arrow ' + (i + 1));
+    return out;
+  });
+}
+
+module.exports = { whenToCondition: whenToCondition, compileTransitions: compileTransitions };

package/lib/flows.js

@@ -200,7 +200,7 @@ function whenToCondition(when, where) {
 /**
  * `{ op, value }` against the engine path `path` → the expression node the
  * engine evaluates. The comparison half of a `when`, shared by every facade
- * that writes conditions (screens flows here, job chains in jobChains.js), so
+ * that writes conditions (screens flows here), so
  * "=" means one thing however a condition arrives.
  *
  * @param {object} when   { op, value }

package/lib/jobs.js

@@ -0,0 +1,144 @@
+// JOBS AND WORKFLOWS — the two places they meet, and nothing more.
+//
+//   a job as a STEP     the job-run step starts a job and parks until it ends
+//   a job as a TRIGGER  a workflow whose trigger is { kind: 'job', jobId }
+//                       starts when that job finishes (lib/triggers.js)
+//
+// Both are ordinary workflows. The host tells this module two things, because
+// only the host knows both products are present: how to start a job
+// (setJobStarter — @xeplr/jobs' trigger()) and that a job has finished
+// (jobFinished — @xeplr/jobs' onFinish hook). This module never imports jobs.
+var triggers = require('./triggers');
+
+// Supplied by the host: async (jobId, { inputs, chain, callbackUrl }) →
+// { occurrenceId }. With @xeplr/jobs in the same process that is
+// `jobs.trigger`. Unset, a job-run step falls back to the jobs API over HTTP.
+var _startJob = null;
+
+function setJobStarter(fn) {
+  _startJob = typeof fn === 'function' ? fn : null;
+}
+
+function jobStarter() { return _startJob; }
+
+function pause(ms) {
+  return new Promise(function(resolve) { var t = setTimeout(resolve, ms); if (t.unref) t.unref(); });
+}
+
+/**
+ * Resume the job-run step that started this job.
+ *
+ * A job can finish before the step that started it has parked — the start is
+ * fire-and-forget, and a quick job ends in milliseconds — and the engine
+ * answers that with RESUME_KEY_NOT_READY rather than routing a step that is
+ * still running. So it is tried again for a few seconds, as @xeplr/jobs' HTTP
+ * callback retries. A key already used (that callback got there first) is a
+ * settled answer.
+ */
+async function resumeStep(key, output, opts) {
+  var runner = require('./workflowRunner');
+  for (var attempt = 0; attempt < 20; attempt++) {
+    try {
+      await runner.resumeByKey(key, output, opts);
+      return true;
+    } catch (err) {
+      if (err.code === 'RESUME_KEY_INVALID') return false;
+      if (err.code !== 'RESUME_KEY_NOT_READY') throw err;
+      await pause(250);
+    }
+  }
+  throw new Error('The step waiting on this job never parked, so it could not be told the job finished.');
+}
+
+/**
+ * What a finished job hands a workflow it triggers, as {trigger.*}:
+ *
+ *   jobId     the job that finished
+ *   status    'success' | 'failed'
+ *   error     its error, when it failed
+ *   output    what its action returned
+ *   window    the period it ran for: the range it was given, or — given
+ *             none — the range its action reports it covered
+ *   given / used  those two ranges separately (@xeplr/jobs' previous.*)
+ *   carry     values carried along from the jobs before it
+ *   path      the jobs that led here, oldest first — for loop protection
+ *
+ * Pure — exported to test.
+ */
+function eventOf(report) {
+  report = report || {};
+  var out = report.output || {};
+  var chain = out.chain || {};
+  var path = Array.isArray(chain.path) ? chain.path.slice() : [];
+  if (out.jobId) path.push(out.jobId);
+  return {
+    jobId: out.jobId || null,
+    status: report.status === 'success' ? 'success' : 'failed',
+    error: report.error || null,
+    output: out.output || null,
+    window: out.window || (out.output && out.output.window) || null,
+    given: out.window || null,
+    used: (out.output && out.output.window) || null,
+    carry: chain.carry && typeof chain.carry === 'object' ? chain.carry : {},
+    path: path
+  };
+}
+
+/**
+ * Called by the host for EVERY job run that ends (@xeplr/jobs' onFinish), in
+ * that job's tenant context, with the jobs envelope { status, error, output }.
+ *
+ * Two things, independently: if a job-run step started this job, resume it;
+ * and start every workflow whose trigger is this job finishing.
+ */
+async function jobFinished(report) {
+  report = report || {};
+  var out = report.output || {};
+  var chain = out.chain || {};
+  var result = { resumed: false, started: [] };
+
+  if (chain.resumeKey) {
+    result.resumed = await resumeStep(chain.resumeKey, out,
+      report.status === 'success' ? {} : { status: 'failed', error: report.error });
+  }
+
+  if (!out.jobId) return result;
+  result.started = await triggers.emit('job', eventOf(report));
+  return result;
+}
+
+/**
+ * What a job-run step hands the job it starts, when its run was itself
+ * started by a job: the period flows on unless the step sets one, the carried
+ * values and the path travel with it, and both of the previous job's ranges
+ * are offered (@xeplr/jobs' previous.given / previous.used). A job already on
+ * the path, or a path at MAX_DEPTH, is refused — that is a loop.
+ *
+ * Pure — exported to test.
+ */
+function nextJobCall(trigger, jobId, inputs, carry) {
+  var t = trigger && trigger.kind === 'job' ? trigger : null;
+  var path = t && Array.isArray(t.path) ? t.path : [];
+  if (path.indexOf(jobId) > -1) {
+    throw new Error('Job ' + jobId + ' has already run in this chain (' + path.concat(jobId).join(' → ') +
+      '), so running it again would loop. Change the workflows so the chain ends.');
+  }
+  if (path.length >= triggers.MAX_DEPTH) {
+    throw new Error('This chain has run ' + path.length + ' jobs in a row, which is the most allowed. Check the workflows for a loop.');
+  }
+  var given = inputs && typeof inputs === 'object' && !Array.isArray(inputs) ? Object.assign({}, inputs) : {};
+  if (t && t.window && given.window === undefined) given = Object.assign({ window: t.window }, given);
+  var carried = Object.assign({}, (t && t.carry) || {}, carry && typeof carry === 'object' ? carry : {});
+  return {
+    inputs: given,
+    chain: { carry: carried, path: path, previous: { given: (t && t.given) || null, used: (t && t.used) || null } }
+  };
+}
+
+module.exports = {
+  setJobStarter: setJobStarter,
+  jobStarter: jobStarter,
+  jobFinished: jobFinished,
+  eventOf: eventOf,
+  nextJobCall: nextJobCall
+};