@xeplr/workflow-engine 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @xeplr/workflow-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The workflow engine, with no HTTP in it.** It owns workflow's database and tables, the action catalog, starting and resuming runs, and the flows facade (screens as steps). [`@xeplr/workflow-api`](https://github.com/Xeplr/xeplr-workflow-api) puts the routes on top.
+
+**Free and open source (MIT, [LICENSE](LICENSE))**, on npm as `@xeplr/workflow-engine` and on GitHub at [Xeplr/xeplr-workflow-engine](https://github.com/Xeplr/xeplr-workflow-engine). With [`@xeplr/workflow-api`](https://github.com/Xeplr/xeplr-workflow-api) it is a complete base to automate with and to build your own workflow screens on: every action in `@xeplr/actions` (databases, files, email…), branching, fan-out, waits, job chains and screens as steps. **X-Flow**, Xeplr's premium workflow product, is built on these two packages and adds the visual designer (steps drawn and connected on a canvas) and data operations between steps; neither is part of this package.
+
+```bash
+npm install @xeplr/workflow-engine
+```
+
+## Use
+
+```js
+var engine = require('@xeplr/workflow-engine');
+
+await engine.startEngine({
+  db: { name: 'xeplr_bi_workflow', connection: conn, connectionName: 'workflow' }
+});
+var run = await engine.runner.startRun(workflowId, params, { user });
+await engine.resumeByKey(key, { confirmedBy: userId });
+```
+
+Most hosts never call this directly: the API's `registerWorkflow()` calls `startEngine()` first and passes `resumeByKey` and the env lists through.
+
+The shared `@xeplr/*` libraries (`actions`, `db`, `expression-handler`, `schema-handler`, `utils`) are **peer dependencies**. The host supplies them, so the engine reads the same tenant context and the same action registry as the host. Two copies of `@xeplr/db` would mean two tenant contexts, and a run started in one would not see the other's company.
+
+## Exports (`index.js`)
+
+| 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) |
+| `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`) |
+| `MIGRATIONS_DIR`, `TENANT_MIGRATIONS_DIR` | Where the SQL is, for the standalone server and for a bundle that ships the folders |
+| `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)) |
+| `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.
+
+## Structure
+
+```
+engine/
+├─ index.js                 startEngine, resumeByKey, the env lists, and the parts below
+├─ 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
+│  ├─ actionCatalog.js      whitelist of @xeplr/actions built-ins + local actions
+│  ├─ actions/              local actions: job-run, screen-show, job-chain-decide/-next
+│  ├─ 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
+├─ migrations-tenants/      0001–0002: standalone workflow's companies / workspaces
+└─ test/                    run.mjs + *.test.mjs
+```
+
+## Data model and migrations
+
+Both run against workflow's own database:
+
+| Directory | Target DB | How it runs |
+|---|---|---|
+| `migrations/` | workflow's own (`DB_API` standalone, `DB_WORKFLOW` in BI) | On every boot inside `startEngine` (and once more in the API's `standalone.js`); idempotent. Also the API's `npm run migrate:up`. Plain `.sql`, ledger-tracked by filename, `precede` order |
+| `migrations-tenants/` | the same | Inside `startEngine` unless `tenantTables: false` |
+
+| Migration | Creates |
+|---|---|
+| `0001_companies` | `companies` (l1 tenant) |
+| `0002_workspaces` | `workspaces` (l2, under a company) |
+| `0003_workflows` | `workflows` — `name`, `description`, `params` (jsonb), `status` (default `draft`) |
+| `0004_workflow_steps` | `workflow_steps` — `stepKey` (unique per workflow), `actionName`, `values`, `kind` (`auto`/`wait`), `timeoutMs`, `onError` (`stop`/`continue`), `transitions`, `joinStep`, `position` |
+| `0005_workflow_runs` | `workflow_runs` — `status` (`queued`/`running`/`waiting`/`success`/`failed`), `params`, `item`, `trigger`, timings, `error` |
+| `0006_workflow_step_runs` | `workflow_step_runs` — copied `stepKey`/`actionName`, resolved `input`, `output`, `error` |
+| `0007_workflow_resume_keys` | `workflow_resume_keys` — unique random `key`, `consumedDate` |
+| `0008_workflow_run_edges` | `workflow_run_edges` — parent → child run for `each` fan-out; `childRunId` unique |
+| `0009` | `workflow_steps.layout` (canvas `{x, y}`) |
+| `0010` | `workflow_steps.sampleOutput` |
+| `0011` | `workflow_steps.params` |
+| `0012` | `workflows.kind` (`workflow` \| `jobs`, default `workflow`) |
+| `0013` | `workflows.key` — a stable name a host addresses a flow by, unique per tenant while it is set |
+| `0014` | `workflows.trigger` (jsonb) — **what is supposed to start a run**, beside what comes in with it. One shape per kind: `{kind:'manual'}`, `{kind:'api'}`, `{kind:'schedule',cron}`, `{kind:'file',folder,named}`, `{kind:'email',mailbox,folder}`. NULL means "started however it is called", so every existing workflow behaves exactly as it did. **Nothing arms these yet** — the designer records the intent; the pollers and the hook endpoint read it when they land |
+
+Every table carries `mtId1`–`mtId4` and **no `applicationId`**: the database a
+host gives workflow is the boundary.
+
+## How a run behaves (`lib/workflowRunner.js`)
+
+- **Step values** are interpolated with `@xeplr/schema-handler` against
+  `{ params, item, steps.<key>.output, previous_step.output, env, resumeKey, resumeUrl }`.
+  `previous_step`/`steps` come from what ran in this run, not array position.
+- **Routing**: no `transitions` → next step by `position`. With transitions →
+  first match wins (`@xeplr/expression-handler`); a blank condition is the
+  catch-all; targets are a `stepKey`, `end_success` or `end_failed`. No match
+  and no catch-all **fails the run**.
+- **Fan-out**: a matching `each` transition creates one child run per matching
+  element (`item`), recorded in `workflow_run_edges`. With `joinStep` the parent
+  waits and resumes at the join once all children are terminal (guarded by an
+  atomic `waiting → running` patch); without it the parent finishes.
+- **Wait steps**: the resume key row is written **before** the action runs;
+  the run parks with status `waiting`. If the action fails the key is marked
+  consumed.
+- **Action failure**: `onError: 'continue'` advances by position; otherwise the
+  run fails.
+- **Run params**: the run schema is the union of every step's `params` (plus
+  legacy `workflows.params` first). Any step requiring a name makes it required;
+  otherwise first declaration by position wins. Validated with `applySchema`
+  **before** the run row is inserted; undeclared keys are dropped; failure has
+  `code: 'PARAMS_INVALID'` and `details`. A workflow that declares nothing
+  accepts params unchanged.
+- **A wait step's own key** reaches its action as `system.resumeKey` (and
+  `{resumeKey}` / `{resumeUrl}` in its values), so an action can hand it to
+  something in the same process instead of over a URL.
+- **Tenant context**: after the first lookup, all DB work runs inside
+  `runWithMt()` with the run's stored `mtId`s, because a resume can arrive long
+  after the starting request.
+
+Not read by the runner: `workflows.status`, `workflows.kind`,
+`workflow_steps.layout`, `workflow_steps.sampleOutput`, `workflow_steps.timeoutMs`.
+
+## Job chains (`lib/jobChains.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>`:
+
+- `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.
+
+A rule is `{ when, run, inputs?, carry? }`:
+
+```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>" }
+]
+```
+
+- **`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.
+
+`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.
+
+**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) });
+```
+
+`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.
+
+## Tests
+
+```bash
+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.
+
+| 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 |
+| `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) |
+| `runParams.test.mjs` | `resolveParams` / `collectParams`: required, defaults, types, typos, union rules |
+
+The flows facade is tested from `@xeplr/workflow-api` (`test/flows.test.mjs`), through its real router.

package/db/xcfgSetup.js

@@ -0,0 +1,8 @@
+// Single shared instance of @xeplr/actions' attachConfig() — so bin/www (which
+// calls ready()) and anything else reading control-plane metadata see the same
+// connection. All the bootstrap/bind/metaStore logic lives in @xeplr/actions;
+// this file is just the one place xeplr-workflow holds its instance, naming
+// itself 'xeplr-workflow'.
+var { attachConfig } = require('@xeplr/actions');
+
+module.exports = attachConfig({ service: 'xeplr-workflow' });

package/index.js

@@ -0,0 +1,290 @@
+var path = require('path');
+var { up } = require('@xeplr/db').sqlMigrator;
+var { resolveConfig, registerApplication, getApplicationId, migrationsFor, ensureDatabaseFor } = require('@xeplr/db');
+var connectDb = require('./lib/db');
+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 xcfgSetup = require('./db/xcfgSetup');
+
+// THE WORKFLOW ENGINE — everything that runs a workflow, with no HTTP in it:
+// its database and tables, the action catalog, starting and resuming runs, and
+// the flows facade (screens as steps). @xeplr/workflow-api puts routes on top
+// of this; a host that only RUNS workflows (a job that starts one, a link that
+// resumes one) can use this alone.
+
+// Where the engine's SQL lives. Exported so a deployment that ships these
+// folders somewhere else (a compiled bundle) and the standalone server read
+// the same paths rather than each re-deriving them.
+var MIGRATIONS_DIR = path.join(__dirname, 'migrations');
+var TENANT_MIGRATIONS_DIR = path.join(__dirname, 'migrations-tenants');
+
+/**
+ * Connect workflow's own database, bring its tables up to date and register
+ * its actions. Idempotent; the API's registerWorkflow() calls it first.
+ *
+ * @param {object} config
+ * @param {object} config.db - { name, connection, mts?, connectionName?, migrationsTable? } —
+ *   see lib/db.js. migrationsTable: workflow's own migration ledger, for a
+ *   database it SHARES with its host (default: @xeplr/db's xeplr_migrations).
+ * @param {boolean} [config.tenantTables=true] - false: do not create
+ *   standalone workflow's own companies / workspaces tables.
+ * @param {string} [config.applicationId] - the PRODUCT running this; see below.
+ * @param {string|string[]} [config.migrations] - a host's extra migrations
+ *   for workflow's database (default: XEPLR_WORKFLOW_MIGRATIONS).
+ * @param {boolean} [config.migrate=true] - false: connect without running
+ *   migrations, for a second process of an install whose API migrates.
+ * @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).
+ */
+async function startEngine(config) {
+  config = config || {};
+  if (config.startJob !== undefined) jobChains.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');
+  }
+  // WORKFLOW'S OWN TABLES CARRY NO applicationId. Each host supplies its own
+  // database (config.db), so that database is the boundary — a column holding
+  // one constant value in every row would buy nothing, which is the same
+  // reason xeplr_bi and the auth DBs do not have one either.
+  //
+  // The identity is still REQUIRED, because this mount also writes to
+  // xeplr_configs — the one store that genuinely is shared by every app and
+  // cannot be split per consumer (reference data, plus import_meta). Rows
+  // there are attributed by applicationId, so a mount that skipped this would
+  // quietly file its movement metadata under the package name instead of the
+  // product's.
+  //
+  // Inherited by default: a host registers itself once at boot and every
+  // sub-product it mounts picks it up with no further wiring. config
+  // .applicationId is accepted for a host that would rather be explicit, and
+  // is idempotent under the same value.
+  if (config.applicationId) registerApplication(config.applicationId);
+  if (!getApplicationId()) {
+    throw new Error(
+      'startEngine: no application registered. Call registerApplication("<this-product>") ' +
+      'from @xeplr/db once at host startup (or pass config.applicationId). It attributes the ' +
+      'rows this mount writes to the SHARED xeplr_configs database; workflow\'s own tables are ' +
+      'separated by having their own database, not by this.');
+  }
+
+  await connectDb(config.db);
+
+  // ITS OWN TABLES, ITS OWN JOB — for the same reason config.db is required in
+  // both modes. This lived in orchestration/standalone.js, so a host that
+  // embedded workflow got a connection to a database with none of workflow's
+  // tables in it, and the first request failed on a missing relation.
+  //
+  // Idempotent, so a host that also runs them loses nothing by this.
+  //
+  // The migrator resolves its connection BY NAME from a registry that
+  // getConnection above does not populate, so the name has to be resolved
+  // explicitly first. Without this an embedded mount died on
+  // 'No resolved config for "WORKFLOW"' and the whole product silently did
+  // not appear — while every /workflow/* path still answered 401, because the
+  // host's auth middleware runs before routing and a missing route never got
+  // the chance to 404.
+  var migrationConnection = config.db.connectionName || 'workflow';
+  await resolveConfig(migrationConnection, config.db.connection);
+
+  // CREATE IT IF IT IS NOT THERE. Each host gives workflow its own database
+  // (xeplr_bi_workflow, xeplr_erp_workflow) — that separation is the entire
+  // isolation model, so pointing a host at a name that does not exist yet is
+  // the NORMAL first boot, not an error state. Without this it failed on
+  // "database does not exist" and every host had to run a manual createdb
+  // that nothing in the config hinted at. Same as @xeplr/email does.
+  // migrate: false — connect only. For a second process of the same install
+  // (BI's separate jobs service) that must not race the API's own migration
+  // run at deploy: the API migrates, this one uses the tables it made.
+  if (config.migrate !== false) {
+    var ensured = await ensureDatabaseFor(config.db.connection, config.db.name);
+    if (ensured.created) console.log('[workflow] created database ' + config.db.name);
+    // XEPLR_WORKFLOW_MIGRATIONS — a host adds its own tables or seed rows to
+    // workflow's database without editing this package. Same convention as
+    // every other xeplr library (see @xeplr/db's app-migrations.js); config
+    // .migrations lets an embedding host pass them directly instead, since a
+    // host that already has the paths in code should not have to route them
+    // back out through the environment.
+    //
+    // SHARING A DATABASE. A host may give workflow its OWN database (BI's
+    // xeplr_bi_workflow) or put it in the host's (an app from @xeplr/cli). In a
+    // shared one, config.db.migrationsTable keeps workflow's record of what ran
+    // apart from the host's — both use @xeplr/db's migrator, and one ledger
+    // would mix the two histories by filename.
+    var ledger = config.db.migrationsTable || undefined;
+
+    // companies / workspaces are STANDALONE workflow's own tenant lists — the
+    // lists behind its "pick a company, then a workspace" screens. Nothing in a
+    // workflow, step or run references them (runs carry mtId1/mtId2 as plain
+    // ids), and an embedded host has its own tenants, or none — so a host says
+    // tenantTables: false and they are not created. That is also what lets
+    // workflow share a database that already has a "companies" table.
+    if (config.tenantTables !== false) {
+      var tenants = await up({
+        db: config.db.name,
+        dir: TENANT_MIGRATIONS_DIR,
+        type: 'precede',
+        connectionName: migrationConnection,
+        tableName: ledger
+      });
+      if (tenants.migrations.length) console.log('[workflow] ran ' + tenants.migrations.length + ' tenant-table migrations');
+    }
+
+    var migrated = await up({
+      db: config.db.name,
+      dir: MIGRATIONS_DIR,
+      extDir: config.migrations || migrationsFor('workflow'),
+      type: 'precede',
+      connectionName: migrationConnection,
+      tableName: ledger
+    });
+    if (migrated.migrations.length) {
+      console.log('[workflow] ran ' + migrated.migrations.length + ' migrations');
+    }
+  }
+
+
+
+  // THE ACTION CATALOG, for the same reason the migrations above moved here.
+  // This lived only in orchestration/standalone.js, so an embedded host got a
+  // mounted product whose registry was empty: GET /actions answered 200 with
+  // an empty list, the step editor's Action dropdown drew nothing, and there
+  // was no error anywhere to explain why — the one failure mode the whitelist
+  // in lib/actionCatalog.js is otherwise careful to make loud.
+  //
+  // Idempotent (register() overwrites by name), so a host that somehow also
+  // registers them loses nothing.
+  //
+  // xeplr_configs is best-effort HERE and fail-fast in standalone, and the
+  // difference is deliberate: standalone owns its whole process and should
+  // refuse to boot half-configured, whereas failing a host's mount over one
+  // action that records movement metadata would take down a product that is
+  // otherwise entirely functional. The warning names what was lost.
+  try {
+    await xcfgSetup.ready();
+  } catch (err) {
+    console.warn('[workflow] xeplr_configs unavailable (' + err.message + ') — actions needing it are not offered');
+  }
+  var registered = actionCatalog.registerAll();
+  console.log('[workflow] registered ' + registered.length + ' actions: ' + registered.join(', '));
+
+  // Say out loud what step templates can read out of the environment. Silent
+  // by default (nothing exposed unless WORKFLOW_ENV_EXPOSED names it), so a
+  // line here means somebody opted in — and a list that accidentally names a
+  // secret is only catchable if it is visible somewhere.
+  envExposed.logExposure();
+
+}
+
+// Env vars a HOST embedding workflow must supply — spread into the host's
+// env.required.js so a missing one fails at startup rather than at mount:
+//
+//   ...require('@xeplr/workflow-engine').embedRequiredEnv,   // DB_WORKFLOW
+//
+// Named `embedRequiredEnv`, not `requiredEnv`, because it is not the same
+// list as this package's OWN standalone process needs (see env.required.js,
+// which uses DB_API for the very same database — a standalone deployment
+// names its own store, an embedded one is given a separate one by its host).
+// Two deployments, two questions, two lists.
+//
+// DB_WORKFLOW only: the SERVER login comes from the shared
+// XEPLR_DB_CONNECTION, and workflow never reads either itself — the host
+// passes both into registerWorkflow({ db }). This list exists so the host is
+// told what to pass before it boots.
+var embedRequiredEnv = [
+  'DB_WORKFLOW'
+];
+
+/**
+ * Resume a run parked on a 'wait' step. THE ENTIRE consumer-side contract for
+ * waiting — the caller never needs to know which run or step the key belongs
+ * to, because that lookup lives in workflow_resume_keys alone.
+ *
+ *   var { resumeByKey } = require('@xeplr/workflow-engine');
+ *   await resumeByKey(key, { confirmedBy: userId });
+ *
+ * SERVER-SIDE, IN-PROCESS, DELIBERATELY. This is not something a browser
+ * calls. The host's own route — the activation link's landing route, the
+ * confirm button's POST — does its own work (activate the account, record the
+ * approval) and then calls this in the same request. The key travels out
+ * bound into that route's URL via `{resumeKey}` and comes back to the host,
+ * never to workflow's own HTTP surface.
+ *
+ * That is the whole reason it is exported here rather than left as a route: a
+ * resume is a step in the host's transaction, not a separate thing a client
+ * is trusted to trigger.
+ *
+ * Throws with `err.code` set, which is what a host should branch on:
+ *
+ *   RESUME_KEY_INVALID    no live key — already used, unknown, or the run is
+ *                         gone. NORMAL for a host route that also serves
+ *                         users who never came from a workflow: catch it and
+ *                         carry on with your own work.
+ *   RESUME_KEY_NOT_READY  the key is real but its step has not parked yet
+ *                         (the action that delivers it is still running).
+ *                         Nothing is consumed — retry shortly.
+ *
+ * Requires startEngine() (or the API's registerWorkflow(), which calls it) to have run in this process: it is what
+ * connects workflow's database, and this reads through that same connection.
+ * Needs no ambient tenant context — the run carries its own mtIds and this
+ * re-enters them itself.
+ *
+ * @param {string} key    the value bound into the step as {resumeKey}
+ * @param {object} [output]  merged into the wait step's output, so later
+ *   steps can read it as {steps.<stepKey>.output.<name>}
+ * @param {object} [opts]
+ * @param {'success'|'failed'} [opts.status]  resolve the step as FAILED rather
+ *   than succeeded — from there the step's own `onError` decides, defaulting
+ *   to stopping the run. Omit for success, which is what every caller that
+ *   predates this means (an approval click, a confirmation link).
+ * @param {object} [opts.error]  recorded on the step run when status is
+ *   'failed'.
+ * @returns {Promise<{ runId: string, stepKey: string, status: string }>}
+ */
+async function resumeByKey(key, output, opts) {
+  return workflowRunner.resumeByKey(key, output, opts);
+}
+
+// REQUIRED ONLY IF YOU USE STEPS THAT CALL SOMETHING OUTSIDE THIS PROCESS —
+// today that is `job-run`. Kept as its own list, the same way @xeplr/email
+// separates `requiredEnv` (sending) from `templatesRequiredEnv` (the template
+// store): a host that only runs self-contained workflows is never made to
+// configure something it does not use.
+//
+// WORKFLOW_PUBLIC_URL is the base a CALLER can reach this service on, mount
+// path included — https://bi.example.com/workflow for an embedded mount. It is
+// what {resumeUrl} is built from, so a step can hand a job an address to
+// report back to.
+//
+// NOT DEFAULTED, and that is the point of it being here rather than having a
+// fallback: a wrong-but-present address gives a job somewhere to POST that
+// nothing is listening on, so the run waits forever on work that actually
+// finished. Unset, {resumeUrl} is null and job-run refuses by name before
+// starting anything.
+var callbackRequiredEnv = [
+  'WORKFLOW_PUBLIC_URL'
+];
+
+module.exports = {
+  startEngine: startEngine,
+  resumeByKey: resumeByKey,
+  embedRequiredEnv: embedRequiredEnv,
+  callbackRequiredEnv: callbackRequiredEnv,
+  MIGRATIONS_DIR: MIGRATIONS_DIR,
+  TENANT_MIGRATIONS_DIR: TENANT_MIGRATIONS_DIR,
+
+  // The parts the API (and a host's own routes) build on.
+  db: connectDb,
+  actionCatalog: actionCatalog,
+  envExposed: envExposed,
+  runner: workflowRunner,
+  flows: flows,
+  jobChains: jobChains,
+  xcfgSetup: xcfgSetup,
+  auth: require('./lib/auth')
+};