@xeplr/workflow-engine 0.0.0-stage → 1.0.1

package/lib/actionCatalog.js

@@ -0,0 +1,197 @@
+// WHAT THIS PRODUCT CAN BIND TOGETHER.
+//
+// @xeplr/actions ships the actions; this file decides which of them THIS app
+// offers, and registers them once at startup (see bin/www). Whatever a workflow
+// step turns out to be, it will name one of these — so the registry is
+// populated before the first request rather than lazily.
+//
+// A deliberate WHITELIST rather than "register everything the package exports",
+// for two reasons. Some built-ins are more dangerous than others —
+// spawnProgram runs arbitrary executables — and offering one should be a
+// decision somebody made, visible in a diff, not a side effect of upgrading a
+// dependency. And several entries in that package are PLACEHOLDERS: modules
+// with a comment saying the implementation is pending and nothing else in them.
+// Registering one would put a name in the catalog, draw it in the step picker,
+// and fail at the moment somebody relied on it.
+//
+// So the list below is names this app WANTS, and readiness is checked against
+// the package rather than assumed. A name that is not ready yet stays in the
+// list, out of the catalog, and lands the day the package implements it.
+var actions = require('@xeplr/actions');
+var xcfgSetup = require('../db/xcfgSetup');
+
+// The keys on @xeplr/actions' `builtins`, not the action names — those are
+// kebab-case and assigned by the modules themselves (`dbFetch` registers as
+// `db-fetch`). Naming the export is what makes this list checkable.
+var WANTED = [
+  'dbFetch',
+  'dbPush',
+  'dbQuery',
+  // Calling a procedure is its own step now — it used to be reachable only by
+  // running a movement, which meant a procedure that returns nothing could not
+  // be run at all.
+  'dbProcedure',
+  'dbListTables',
+  'dbListViews',
+  'dbListProcedures',
+  'dbListColumns',
+  'fileMove',
+
+  // Email. The five inbound ones are what a workflow monitors a mailbox with;
+  // emailSend is also what a `wait` step uses to deliver its own resume link
+  // (see workflowRunner's mintResumeKey — the key is available to the step's
+  // own action as {resumeKey}).
+  //
+  // emailDelete is offered but worth knowing about: it is a permanent expunge,
+  // not a move to Trash. emailMove to a trash folder is the reversible one.
+  'emailRead',
+  'emailMove',
+  'emailDelete',
+  'emailDownloadEmail',
+  'emailDownloadAttachments',
+  'sendEmail'
+];
+
+// THIS APP'S OWN ACTIONS — not from @xeplr/actions, and not placeholders.
+//
+// Glue between two products, which is exactly why it is not in the shared
+// action library: @xeplr/actions must not learn what a job is. Registered the
+// 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')
+];
+
+// REGISTERED BUT NOT OFFERED.
+//
+// An action a step can legitimately name, that no author should ever pick off
+// a palette. The registry must have it — the engine resolves a step's
+// actionName through the registry, so a step naming an unregistered action
+// cannot run at all — but catalog() leaves it out, because the only thing that
+// knows how to build one of these steps is the facade that owns them.
+//
+// `screen-show` is the case: a screens flow's steps are generated by
+// lib/flows.js from a design held in another app, and one dropped by hand onto
+// the ordinary workflow canvas would park its run forever — nothing outside
+// 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
+];
+
+var HIDDEN_NAMES = HIDDEN.map(function(def) { return def.name; });
+
+// Needs the control-plane connection to record what moved where, so it is
+// registered separately once xcfgSetup has resolved.
+var WANTED_WITH_META = ['fileUpload'];
+
+// DELIBERATELY ABSENT: spawnProgram. It runs arbitrary executables, which is a
+// different kind of permission from "call an HTTP endpoint" — named here so
+// that leaving it out reads as a decision rather than an oversight.
+
+/** A module the registry will actually accept, as opposed to a placeholder. */
+function isReady(def) {
+  return Boolean(def && typeof def.execute === 'function' && def.name);
+}
+
+function offer(key, def, registered, skipped) {
+  if (!isReady(def)) { skipped.push(key); return; }
+  actions.register(def);
+  registered.push(def.name);
+}
+
+/**
+ * Registers this app's actions and returns their names.
+ *
+ * Idempotent — @xeplr/actions' register() overwrites by name, so calling this
+ * twice leaves the registry in the same state rather than doubling it.
+ */
+function registerAll() {
+  var registered = [];
+  var skipped = [];
+
+  WANTED.forEach(function(key) {
+    offer(key, actions.builtins[key], registered, skipped);
+  });
+
+  LOCAL.forEach(function(def) {
+    offer(def.name, def, registered, skipped);
+  });
+
+  // Same registration, no catalog entry — see HIDDEN.
+  HIDDEN.forEach(function(def) {
+    offer(def.name, def, registered, skipped);
+  });
+
+  WANTED_WITH_META.forEach(function(key) {
+    var entry = actions.builtins[key];
+    // Factory-shaped in some versions, a plain module in others. Both are
+    // handled rather than asserted, because which one it is is the package's
+    // business and not worth breaking a boot over.
+    //
+    // Guarded because reading xcfgSetup.metaStore THROWS when the
+    // control-plane connection was never established — which is a real state
+    // for an embedded host (see registerWorkflow, where xeplr_configs is
+    // best-effort). Losing one action to that is correct; losing the whole
+    // catalog, and with it every other action, is not.
+    try {
+      var def = typeof entry === 'function' ? entry({ metaKnex: xcfgSetup.metaStore }) : entry;
+      offer(key, def, registered, skipped);
+    } catch (err) {
+      console.warn('[actions] ' + key + ' could not be registered: ' + err.message);
+      skipped.push(key);
+    }
+  });
+
+  // Said out loud, once, at startup. A name silently missing from the picker is
+  // a bug somebody spends an afternoon on; a line in the boot log is not.
+  if (skipped.length) {
+    console.warn('[actions] not yet implemented in @xeplr/actions, so not offered: ' + skipped.join(', '));
+  }
+
+  return registered;
+}
+
+/**
+ * The catalog, as the UI needs it: name, description and the INPUT SCHEMA that
+ * describes what each one takes.
+ *
+ * The schema is the point. A step editor told separately what an action accepts
+ * is a second description of it, and the day the two disagree the form collects
+ * a field the action ignores. Sending the registry's own schema means the form
+ * is generated from the thing it is a form for.
+ *
+ * The EXECUTOR is not sent, and could not usefully be — it is a function, it
+ * would not survive JSON, and an endpoint that hands out executors is an
+ * endpoint that explains how to bypass itself.
+ */
+function catalog() {
+  return actions.list().filter(function(a) {
+    // HIDDEN is registered, so the engine can run a step that names it, and
+    // absent here, so no palette ever draws it. Filtered at the point the list
+    // leaves the process rather than by not registering it — the two questions
+    // ("can this run" and "should anyone pick it") have different answers.
+    return HIDDEN_NAMES.indexOf(a.name) === -1;
+  }).map(function(a) {
+    return {
+      name: a.name,
+      description: a.description,
+      inputSchema: a.inputSchema,
+      outputSchema: a.outputSchema
+    };
+  });
+}
+
+module.exports = {
+  registerAll: registerAll,
+  catalog: catalog,
+  isReady: isReady,
+  WANTED: WANTED,
+  WANTED_WITH_META: WANTED_WITH_META,
+  LOCAL: LOCAL,
+  HIDDEN: HIDDEN
+};

package/lib/actions/jobChainSteps.js

@@ -0,0 +1,79 @@
+// THE TWO STEPS OF A JOB CHAIN — see lib/jobChains.js.
+//
+// Registered but HIDDEN from GET /actions, like screen-show: only the facade
+// that generates a chain's workflow knows how to build these steps, and one
+// dropped onto the canvas by hand would have no rules and no finished job to
+// read.
+
+var db = require('../db');
+var jobChains = require('../jobChains');
+
+var NOT_CONNECTED =
+  'This step starts a job, but this install has not connected jobs to workflow. ' +
+  'The host must pass startJob to startEngine()/registerWorkflow() — with @xeplr/jobs ' +
+  'in the same process that is (jobId, body) => jobs.trigger(jobId, body).';
+
+// `decide` does nothing. Its transitions are the job's rules, and the engine
+// evaluates them against the run's params once it returns.
+var decide = {
+  name: jobChains.DECIDE_ACTION,
+  description: 'Choose which job runs next from how the last one ended. Its transitions are the rules.',
+  requires: [],
+  inputSchema: [{ name: 'rules', type: 'array', order: 1, description: 'The rules as written on the job.' }],
+  outputSchema: null,
+  execute: async function() { return {}; }
+};
+
+// `run_n` starts one job and parks until it reports back. The rule's inputs and
+// carry are resolved HERE against the run's own params (typed — see
+// resolveTyped), not by the engine's text interpolation, so a window or a
+// number passes as itself.
+var next = {
+  name: jobChains.NEXT_ACTION,
+  description: 'Start the next job of a chain with the period and values carried so far, and wait for it.',
+  requires: [],
+  inputSchema: [
+    { name: 'jobId', type: 'string', required: true, order: 1 },
+    { name: 'inputs', type: 'object', order: 2 },
+    { name: 'carry', type: 'object', order: 3 },
+    { name: 'callbackUrl', type: 'string', order: 4 }
+  ],
+  outputSchema: null,
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var startJob = jobChains.jobStarter();
+    if (!startJob) throw new Error(NOT_CONNECTED);
+
+    // The STEP's values as saved, not the interpolated input: `inputs` and
+    // `carry` hold `{output.x}` bindings that only resolveTyped keeps typed.
+    var step = await db.model('WorkflowStep').query().findById(ctx.system.stepId);
+    var run = await db.model('WorkflowRun').query().findById(ctx.system.runId);
+    var call = jobChains.nextJobCall(run && run.params, {
+      jobId: input.jobId,
+      inputs: step && step.values ? step.values.inputs : input.inputs,
+      carry: step && step.values ? step.values.carry : input.carry
+    });
+
+    // The resume key travels in the chain, so a host can resume this step
+    // in-process when the job ends (jobChains.jobFinished); the callback URL
+    // is the same key over HTTP, for a jobs service in another process. Null
+    // when WORKFLOW_PUBLIC_URL is unset, which is fine in-process.
+    call.chain.resumeKey = (ctx.system && ctx.system.resumeKey) || null;
+    var started = await startJob(input.jobId, {
+      inputs: call.inputs,
+      chain: call.chain,
+      callbackUrl: input.callbackUrl || null
+    });
+
+    return {
+      jobId: input.jobId,
+      occurrenceId: (started && started.occurrenceId) || null,
+      status: 'running',
+      window: call.inputs.window || null,
+      carry: call.chain.carry
+    };
+  }
+};
+
+module.exports = { decide: decide, next: next };

package/lib/actions/jobRun.js

@@ -0,0 +1,171 @@
+// 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
+// two HTTP calls' worth of glue between two products that do not import each
+// other:
+//
+//   1. POST <jobsUrl>/jobs/<jobId>/trigger  { inputs, callbackUrl }
+//   2. return — the STEP does not finish here. It is a `wait` step, so the run
+//      parks, and @xeplr/jobs POSTs the outcome to callbackUrl when the
+//      occurrence reaches a terminal state, which resumes it.
+//
+// ── why it does not wait for the job ─────────────────────────────────────
+//
+// A movement runs for twenty minutes. Holding an await open across that would
+// tie a run's progress to one process staying alive, and a deploy in the
+// middle would lose it with nothing recording why. The resume key is a row in
+// a table: it survives a restart, and it is the same mechanism an emailed
+// approval link has always used.
+//
+// ── THIS IS TEMPORARY, AND SHOULD BE DELETED ─────────────────────────────
+//
+// Nothing here is about jobs except the URL shape and the field named
+// `callbackUrl`. The general form is @xeplr/actions' `http-request` (today a
+// placeholder) called from a wait step with `{resumeUrl}` bound into its body,
+// which would serve jobs, saved API calls and anything else that can honour
+// the callback contract. This exists so the jobs canvas can be finished
+// first; when http-request lands, a job step becomes a configuration of it and
+// this file goes away.
+//
+// It lives in xeplr-workflow rather than in @xeplr/actions deliberately: it is
+// glue between two products, and putting it in the shared action library would
+// teach that library what a job is.
+
+var CALLBACK_UNREACHABLE =
+  'This step starts a job and waits for it to report back, but WORKFLOW_PUBLIC_URL ' +
+  'is not set, so there is no address to give the job to call. Set it to the base ' +
+  'URL this service is reachable on (including any mount path — e.g. ' +
+  'https://bi.example.com/workflow) and run this again.';
+
+module.exports = {
+  name: 'job-run',
+  description: 'Run a saved job and wait for it to finish. The job reports its outcome back, ' +
+               'so the next step runs only once it has actually completed.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'jobsUrl', type: 'string', order: 1,
+      description: 'Base URL of the jobs API — e.g. https://bi.example.com/api. Not needed when ' +
+                   'the host connected jobs in-process (startEngine\'s startJob).' },
+    { name: 'jobId', type: 'string', required: true, order: 2,
+      description: 'The job to run.' },
+    { name: 'callbackUrl', type: 'string', order: 3,
+      description: 'Where the job reports its outcome. Bind this to {resumeUrl}; it is the ' +
+                   'address of this step\'s own resume key. Needed only when the job is started ' +
+                   'over HTTP — an in-process start reports back through the same key directly.' },
+    { 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',
+      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.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+
+    // THE HOST'S OWN WAY OF STARTING A JOB, when it gave one (startEngine's
+    // startJob — @xeplr/jobs' trigger() in the same process). No HTTP, no
+    // 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();
+    if (startJob) {
+      var started = await startJob(input.jobId, {
+        inputs: input.inputs || null,
+        callbackUrl: input.callbackUrl || null,
+        chain: { resumeKey: (ctx.system && ctx.system.resumeKey) || null }
+      });
+      return {
+        jobId: input.jobId,
+        occurrenceId: (started && started.occurrenceId) || null,
+        startedAt: new Date().toISOString(),
+        status: 'running'
+      };
+    }
+
+    // The binding resolved to nothing, which means WORKFLOW_PUBLIC_URL is
+    // unset (see workflowRunner's publicResumeUrl). Caught HERE, before the
+    // job is started, because the alternative is a job that runs perfectly for
+    // twenty minutes and then has nowhere to report to — leaving the step
+    // waiting forever on work that actually succeeded.
+    if (!input.callbackUrl) throw new Error(CALLBACK_UNREACHABLE);
+
+    // THE SAME CHECK FOR THE OTHER BINDING, and it needs its own message.
+    //
+    // The canvas fills jobsUrl with `{env.JOBS_API_URL}`, and the engine
+    // resolves an unknown binding to the EMPTY STRING rather than failing —
+    // so an unset (or unexposed) variable arrives here as '' and satisfies
+    // `required`, which only rejects null and undefined. Left alone that
+    // becomes fetch('/jobs/j1/trigger') and a "Failed to parse URL" nobody can
+    // trace back to an environment variable.
+    //
+    // Both halves are named because either one alone is the cause: the
+    // variable can be set and simply not listed in WORKFLOW_ENV_EXPOSED, which
+    // is exactly as invisible.
+    var jobsUrl = String(input.jobsUrl || '').trim();
+    if (!/^https?:\/\//i.test(jobsUrl)) {
+      throw new Error('This step needs the address of the jobs API and got ' +
+        (jobsUrl ? '"' + jobsUrl + '"' : 'nothing') + '. It is normally bound to ' +
+        '{env.JOBS_API_URL}, which resolves to an empty string unless JOBS_API_URL is set ' +
+        'AND named in WORKFLOW_ENV_EXPOSED — check both. It must be absolute, e.g. ' +
+        'https://bi.example.com/api');
+    }
+
+    var base = jobsUrl.replace(/\/+$/, '');
+    var url = base + '/jobs/' + encodeURIComponent(input.jobId) + '/trigger';
+
+    var controller = new AbortController();
+    var timer = setTimeout(function() { controller.abort(); }, input.timeoutMs || 30000);
+    if (timer.unref) timer.unref();
+
+    var res;
+    try {
+      res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          inputs: input.inputs || undefined,
+          callbackUrl: input.callbackUrl
+        }),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    // BUSY IS A FAILURE, NOT A WAIT.
+    //
+    // A job holds one lock and runs one at a time. Treating 409 as "try again
+    // shortly" would mean a chain that quietly continues past a movement that
+    // never ran, and the step after it aggregating a period nothing loaded.
+    // Failing here stops the run, which is what the step's own onError already
+    // defaults to.
+    if (res.status === 409) {
+      throw new Error('Job ' + input.jobId + ' is already running, so this step cannot start it. ' +
+        'Wait for the current run to finish, or schedule these so they do not overlap.');
+    }
+
+    if (!res.ok) {
+      var detail = await res.text().catch(function() { return ''; });
+      throw new Error('Could not start job ' + input.jobId + ' — the jobs API answered ' +
+        res.status + (detail ? ': ' + detail.slice(0, 300) : '') + '.');
+    }
+
+    var body = await res.json().catch(function() { return {}; });
+    var row = (body.dataArray && body.dataArray[0]) || {};
+
+    // WHAT THIS STEP KNOWS SO FAR — the handle, not the result.
+    //
+    // The occurrence's outcome arrives later, through the callback, and
+    // resumeByKey MERGES it over this. So a downstream binding of
+    // {steps.<key>.output.occurrenceId} works from the moment the job starts,
+    // and {steps.<key>.output.output.totalRows} works once it has finished.
+    return {
+      jobId: input.jobId,
+      occurrenceId: row.occurrenceId || null,
+      startedAt: new Date().toISOString(),
+      status: 'running'
+    };
+  }
+};

package/lib/actions/screenShow.js

@@ -0,0 +1,71 @@
+// screen-show — PARK THE RUN AND LET A PERSON FILL IN A SCREEN.
+//
+// The step behind every node of a 'screens' flow (see lib/flows.js). It is a
+// `wait` step whose action does nothing at all, and the nothing is the whole
+// design:
+//
+//   1. the engine mints the resume key BEFORE the action runs (see
+//      workflowRunner's executeFrom) and parks the run at status 'waiting';
+//   2. this returns immediately, so there is nothing to undo and nothing that
+//      can fail between "the person opened the screen" and "the run is
+//      waiting for them";
+//   3. the person submits; POST /flows/runs/:runId/submit resumes the step
+//      with what they typed, and resumeByKey MERGES that onto this output.
+//
+// ── why it returns {} and not { screen } ─────────────────────────────────
+//
+// The step's output IS the submitted values, and nothing else. Transitions on
+// a screens flow read `output.<field>` where <field> is a field of the screen,
+// so anything this action put in the output would occupy a name a screen might
+// legitimately use — a screen with a field called `screen` would then branch on
+// this action's own bookkeeping until the moment it was submitted.
+//
+// Which screen was shown is not lost by returning nothing: the resolved input
+// is persisted on the step run (workflow_step_runs.input), so history records
+// it, and the facade reads the screen off the STEP row (values.screen) rather
+// than off a run, because that is where the flow's design lives.
+//
+// ── why it is not in the action palette ──────────────────────────────────
+//
+// It is registered (the engine resolves a step's actionName through the
+// registry, so a step could not run without it) but hidden from GET /actions —
+// see lib/actionCatalog.js's HIDDEN. Dropping one onto the ordinary workflow
+// canvas would produce a step that parks forever: nothing outside the flows
+// facade knows how to show a screen or how to resume it.
+
+module.exports = {
+  name: 'screen-show',
+  description: 'Show a screen to a person and wait for them to submit it. The values they ' +
+               'submit become this step\'s output, so a transition can branch on them.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'screen', type: 'string', required: true, order: 1,
+      description: 'Key of the screen to show. The app that owns the screens resolves it; ' +
+                   'this engine only carries it.' },
+
+    // WHAT THE SCREEN OPENS WITH — an ordinary step input, resolved by
+    // interpolateAll before this runs, like an email's `to`.
+    //
+    // A screen can declare that a field is filled in by whoever opens the form
+    // (@xeplr/ui-factory's `filledBy: 'caller'`): a containment's complaint is
+    // known by the flow and is not a question for the person. This is where
+    // the flow answers it — { complaintId: '{steps.d1.output.recordId}' } —
+    // and the values arrive already substituted, so the facade hands the app a
+    // plain object and nothing downstream knows what a token is.
+    //
+    // Not called "prefill": it is the step's input, and a screen step is an
+    // ordinary step whose action happens to park the run.
+    { name: 'values', type: 'object', order: 2,
+      description: 'What the screen starts with — the fields it says are filled in by ' +
+                   'whoever opens it. A person is not asked for these.' }
+  ],
+
+  // Whatever the person submitted, which is not knowable from here — declared
+  // as nothing rather than as a lie. See the note above.
+  outputSchema: null,
+
+  execute: async function() {
+    return {};
+  }
+};

package/lib/auth.js

@@ -0,0 +1,19 @@
+// THE AUTH DATABASE, for the hooks that grant a creator access to the company
+// or workspace they just made (models/Company.js, models/Workspace.js) — the
+// standalone server's own tenant screens. An embedded host has its own
+// tenants and never inserts these rows.
+//
+// One connection per process, opened on first use: @xeplr/auth's attach()
+// opens a new one every time it is called, and the standalone server reads
+// the same database (orchestration/standalone.js uses this too).
+var _auth = null;
+
+function get() {
+  if (!_auth) _auth = require('@xeplr/auth').attach();
+  return _auth;
+}
+
+module.exports = {
+  ready: function() { return get().ready(); },
+  model: function(name) { return get().model(name); }
+};

package/lib/db.js

@@ -0,0 +1,82 @@
+var { getConnection, registerMTs } = require('@xeplr/db');
+var models = require('../models');
+
+var _registered = false;
+var _conn = null;
+
+/**
+ * Bind workflow's own models to a connection. Config-driven — never reads
+ * process.env; that is orchestration/standalone.js's job when nothing else
+ * supplies one.
+ *
+ * @param {object} config
+ * @param {string} config.name - database name (workflow's OWN domain data —
+ *   this is always workflow's responsibility, embedded or standalone; that
+ *   data belongs to workflow, not whatever it's mounted into)
+ * @param {string} config.connection - connection string/encrypted blob, same
+ *   shape @xeplr/db's getConnection already expects
+ * @param {object} [config.mts] - { l1: {name, header}, ... }. registerMTs()
+ *   is PROCESS-GLOBAL — only pass this when nothing else in this process has
+ *   already called it. A host app embedding workflow has already registered
+ *   its own levels; passing config.mts in that case would silently overwrite
+ *   them. Standalone mode passes it; registerWorkflow's embedded branch does
+ *   not.
+ */
+async function connectDb(config) {
+  config = config || {};
+  if (!config.name || !config.connection) {
+    throw new Error('connectDb: { name, connection } are required');
+  }
+  if (config.mts && !_registered) {
+    registerMTs(config.mts);
+    _registered = true;
+  }
+
+  // bind:false — A SECONDARY CONNECTION, never the process's global one.
+  //
+  // @xeplr/db's bindModels does `Model.knex(instance)` on OBJECTION'S BASE
+  // CLASS, so it is global: the last getConnection with bind:true wins for
+  // every model in the process, whoever declared it. Standalone that is
+  // harmless, because workflow is the only thing here. Embedded it is not —
+  // connecting to workflow's own database re-pointed the HOST's models at it
+  // too, and the host's own routes started failing on tables that were never
+  // in this database.
+  //
+  // So workflow binds its OWN models to its OWN connection and leaves the
+  // global binding alone. Exactly what @xeplr/auth's attach() does to reach
+  // the auth database from the api process, and what @xeplr/actions'
+  // attachConfig() does for xeplr_configs — this is the third instance of the
+  // same shape, not a new idea.
+  _conn = await getConnection(config.name, config.connection, {
+    bind: false,
+    connectionName: config.connectionName || 'workflow'
+  });
+  return _conn;
+}
+
+function conn() {
+  if (!_conn) throw new Error('workflow: connection not ready — await connectDb() first');
+  return _conn;
+}
+
+/**
+ * A workflow model BOUND to workflow's own connection.
+ *
+ * Every query in this package goes through here rather than through the class
+ * exported by models/index.js. An unbound class falls back to the global
+ * binding, which belongs to whatever else is in this process — the host app,
+ * embedded — so it would read the wrong database and mostly report that
+ * workflow's tables do not exist.
+ *
+ * Objection caches per (Model, knex) pair, so calling this per request costs a
+ * map lookup rather than a new class.
+ */
+function model(name) {
+  var M = models[name];
+  if (!M) throw new Error('workflow: unknown model "' + name + '"');
+  return M.bindKnex(conn());
+}
+
+module.exports = connectDb;
+module.exports.conn = conn;
+module.exports.model = model;