@xeplr/workflow 1.0.1

package/migrations/0002_workspaces.sql

@@ -0,0 +1,22 @@
+-- 0002_workspaces.sql
+-- workspaces — the second tenancy level, under a company (mtId2 on every row
+-- that lives inside one). Where a team's workflows are organised.
+
+CREATE TABLE "workspaces" (
+  "id" varchar(25) PRIMARY KEY,
+  "companyId" varchar(25) NOT NULL,
+  "name" varchar(255) NOT NULL,
+  "description" varchar(500),
+  "tags" jsonb,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "workspaces_company_index" ON "workspaces" ("companyId");

package/migrations/0003_workflows.sql

@@ -0,0 +1,35 @@
+-- 0003_workflows.sql
+-- workflows — the product's one document. A workflow is an ordered list of
+-- steps, and a step names a registered @xeplr/actions action plus the input to
+-- call it with. Binding actions together is the whole of what this app does;
+-- everything else exists to make that list savable, runnable and auditable.
+--
+-- `params` are the workflow's own declared inputs — what a caller supplies at
+-- run time (a file path, a customer id). Steps reference them as `{params.x}`
+-- in a bound value, so the same workflow runs against different subjects
+-- without being edited.
+
+CREATE TABLE "workflows" (
+  "id" varchar(25) PRIMARY KEY,
+  "name" varchar(255) NOT NULL,
+  "description" varchar(1000),
+  -- Declared inputs: [{ name, type, required, default, description, order }] —
+  -- the same shape @xeplr/actions uses for an action's inputSchema, so a
+  -- workflow reads as an action made of actions.
+  "params" jsonb,
+  -- Draft workflows are editable and not runnable; published ones are what a
+  -- trigger is allowed to start. One column rather than a separate table
+  -- because it is a property of the workflow, not a thing of its own.
+  "status" varchar(20) DEFAULT 'draft',
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "workflows_status_index" ON "workflows" ("status");

package/migrations/0004_workflow_steps.sql

@@ -0,0 +1,79 @@
+-- 0004_workflow_steps.sql
+-- workflow_steps — one call to one registered action, plus what happens after
+-- it. `actionName` is a REFERENCE INTO THE @xeplr/actions REGISTRY, not a copy
+-- of the action: no code, no endpoint, no credentials live here. A step whose
+-- action the registry does not have cannot run, which is reported rather than
+-- guessed at.
+--
+-- `values` is the argument object, and its string values may carry
+-- placeholders — `{previous_step.output.x}`, `{steps.<key>.output.x}`,
+-- `{params.x}`, and for a `kind = 'wait'` step, `{resumeKey}` — resolved by
+-- @xeplr/schema-handler's templating against the run's context before the
+-- action is called.
+--
+-- `kind`: 'auto' runs and advances the moment it finishes; 'wait' pauses the
+-- run after starting — the command it calls is responsible for eventually
+-- resolving the pause via workflowRunner.resumeByKey(key, output). See
+-- 0007_workflow_resume_keys.sql for how that key is tracked.
+--
+-- `transitions` is an ordered array of
+--   { condition, mode: 'single' | 'each', target }
+-- evaluated top to bottom — first match wins. `condition` is a structured
+-- @xeplr/expression-handler expression ({ left, op, right }) or null/absent,
+-- which always matches (the catch-all row). `target` is another step's
+-- `stepKey`, or the sentinel 'end_success' / 'end_failed'. A step with no
+-- transitions at all keeps the old default: advance to the next step by
+-- `position`. A step WITH transitions that finds no match (and has no
+-- catch-all row) fails — silently falling through would hide a branch nobody
+-- accounted for.
+--
+-- A transition marked 'each' fans the rest of that branch out once per
+-- matching element instead of running it once — see workflow_run_edges for
+-- how the resulting child runs relate back to this one. `joinStep`, if set,
+-- names a step to run a single time once every one of those children has
+-- finished (e.g. batch-move everything that was downloaded, instead of once
+-- per item); only meaningful when at least one transition here is 'each'.
+--
+-- `onError` is unrelated to transitions — it governs what happens when the
+-- action call itself throws (bad input, unreachable endpoint), not how a
+-- successful result is routed: 'stop' (default) halts the run, 'continue'
+-- lets the rest of the steps proceed regardless.
+--
+-- `stepKey` is how another step's transition or a later step's bound value
+-- addresses this one. Author-facing and stable across reordering, which
+-- `position` is not — insert a step in the middle and every position below it
+-- changes, so a reference by position would silently start reading a
+-- different step's output.
+
+CREATE TABLE "workflow_steps" (
+  "id" varchar(25) PRIMARY KEY,
+  "workflowId" varchar(25) NOT NULL,
+  "stepKey" varchar(64) NOT NULL,
+  "name" varchar(255),
+  "actionName" varchar(128) NOT NULL,
+  "values" jsonb,
+  -- auto · wait
+  "kind" varchar(20) NOT NULL DEFAULT 'auto',
+  -- Only meaningful for kind = 'wait'. Milliseconds; null means no expiry.
+  "timeoutMs" integer,
+  -- stop · continue — what an execution failure of THIS step means for the
+  -- rest of the run.
+  "onError" varchar(20) DEFAULT 'stop',
+  "transitions" jsonb,
+  "joinStep" varchar(64),
+  "position" integer DEFAULT 0,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "workflow_steps_workflow_index" ON "workflow_steps" ("workflowId");
+-- Two steps with one key would make a `steps.<key>.output` reference (and a
+-- transition `target`) ambiguous — resolving to whichever the reader picks.
+CREATE UNIQUE INDEX "workflow_steps_key_unique" ON "workflow_steps" ("workflowId", "stepKey");

package/migrations/0005_workflow_runs.sql

@@ -0,0 +1,49 @@
+-- 0005_workflow_runs.sql
+-- workflow_runs — one occurrence of one workflow: the thread that ties a
+-- send-and-wait email, a UI form render, and everything that resumes them
+-- back together. Persisted rather than kept in memory, because "what did this
+-- do last night" is the question a workflow product exists to answer, and a
+-- run that only lives in a process is a run nobody can look at after a
+-- restart or a crash mid-wait.
+--
+-- `params` records the values the run was STARTED WITH, so a result can be
+-- reproduced — re-resolving them later would read today's defaults over
+-- yesterday's run.
+--
+-- `item` is set only on a CHILD run — the one element (out of however many an
+-- 'each' transition matched) this particular occurrence exists to process.
+-- Denormalized here for the runner's own hot-path reads; workflow_run_edges
+-- is still the source of truth for the parent/child relationship and its
+-- provenance (which step fanned out, which position this was).
+--
+-- `status`: queued · running · waiting · success · failed. 'waiting' is
+-- distinct from 'running' — it means the run is paused on a wait step with a
+-- live entry in workflow_resume_keys, not actively doing anything.
+
+CREATE TABLE "workflow_runs" (
+  "id" varchar(25) PRIMARY KEY,
+  "workflowId" varchar(25) NOT NULL,
+  "status" varchar(20) NOT NULL DEFAULT 'queued',
+  "params" jsonb,
+  "item" jsonb,
+  -- Who or what asked: 'manual', or the name of whatever triggers it later.
+  "trigger" varchar(64) DEFAULT 'manual',
+  "startedAt" timestamp,
+  "finishedAt" timestamp,
+  "durationMs" integer,
+  -- The failure that ended the run, if one did. Per-step detail lives in
+  -- workflow_step_runs; this is the summary a list needs without a join.
+  "error" jsonb,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "workflow_runs_workflow_index" ON "workflow_runs" ("workflowId");
+CREATE INDEX "workflow_runs_status_index" ON "workflow_runs" ("status");

package/migrations/0006_workflow_step_runs.sql

@@ -0,0 +1,42 @@
+-- 0006_workflow_step_runs.sql
+-- workflow_step_runs — what each step actually did while a run happened.
+--
+-- `stepKey` / `actionName` are COPIED from the step, not joined to it. A step
+-- can be renamed, re-pointed at another action, or deleted after this ran;
+-- the history has to keep saying what actually happened, which a join would
+-- quietly rewrite out from under it.
+--
+-- `input` is the values object AFTER placeholders were resolved — what the
+-- action was really called with, the only version worth keeping when a run
+-- has gone wrong for reasons the template explains.
+--
+-- `status`: pending · running · waiting · success · failed · skipped.
+-- 'waiting' mirrors the run's own status while this step holds a live
+-- workflow_resume_keys row. 'skipped' is for a step a transition jumped over
+-- — it never ran, and saying so plainly is the point of listing it as a
+-- distinct status rather than leaving it absent.
+
+CREATE TABLE "workflow_step_runs" (
+  "id" varchar(25) PRIMARY KEY,
+  "runId" varchar(25) NOT NULL,
+  "stepId" varchar(25),
+  "stepKey" varchar(64),
+  "actionName" varchar(128),
+  "status" varchar(20) NOT NULL DEFAULT 'pending',
+  "input" jsonb,
+  "output" jsonb,
+  "error" jsonb,
+  "durationMs" integer,
+  "position" integer DEFAULT 0,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "workflow_step_runs_run_index" ON "workflow_step_runs" ("runId");

package/migrations/0007_workflow_resume_keys.sql

@@ -0,0 +1,42 @@
+-- 0007_workflow_resume_keys.sql
+-- workflow_resume_keys — the whole mechanism behind a 'wait' step, in one
+-- table. When a wait step starts, the engine mints a random opaque `key`
+-- here (NOT encrypted, NOT signed — just a securely random, one-time id, same
+-- as every other row's `id` in this app) and hands it to the step's own
+-- values as `{resumeKey}`, so the command can embed it wherever its channel
+-- needs it: a confirmation link, a hidden field, an approval URL.
+--
+-- The consumer-side contract is exactly one call:
+--   workflowRunner.resumeByKey(key, output)
+-- It never needs to know which run or step the key belongs to — that lookup
+-- lives entirely in this table, keyed by `key` alone. This is what lets
+-- fan-out (see workflow_run_edges) work with zero changes to this mechanism:
+-- once each matching item is its own child run, each one only ever has ONE
+-- live pending key at a time, so there is never a collision to resolve.
+--
+-- `consumedDate` is set the moment resumeByKey succeeds OR the run advances
+-- past this step by any other path (a transition routing elsewhere, the step
+-- timing out) — a consumed or superseded key must not resolve a second call,
+-- whether that call is a genuine retry or a stale/replayed link (an email
+-- security scanner pre-fetching a confirmation URL is the case this is
+-- actually for).
+
+CREATE TABLE "workflow_resume_keys" (
+  "id" varchar(25) PRIMARY KEY,
+  "runId" varchar(25) NOT NULL,
+  "stepId" varchar(25) NOT NULL,
+  "key" varchar(64) NOT NULL,
+  "consumedDate" timestamp,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE UNIQUE INDEX "workflow_resume_keys_key_unique" ON "workflow_resume_keys" ("key");
+CREATE INDEX "workflow_resume_keys_run_index" ON "workflow_resume_keys" ("runId");

package/migrations/0008_workflow_run_edges.sql

@@ -0,0 +1,43 @@
+-- 0008_workflow_run_edges.sql
+-- workflow_run_edges — the ONLY place a workflow run's family tree lives.
+-- workflow_steps stays flat by design (fan-out is a run-time decision, never
+-- an authoring-time one — see the 'each' transition mode in
+-- 0004_workflow_steps.sql), so nothing about a run's ancestry belongs on the
+-- step definition. This table is the edge itself: one row per parent → child
+-- run relationship, created once when an 'each' transition matches more than
+-- zero elements.
+--
+-- `sourceStepKey` names which step's transition did the fanning out, so a
+-- parent's timeline can say "this child came from check_unread_mail" without
+-- guessing. `itemIndex` / `itemKey` position the child within that fan-out —
+-- `itemKey` is a stable identifier from the item itself when one exists (an
+-- email's message-id, say) rather than just an index, so a retry or a re-run
+-- can still tell which item is which. `item` is the same value the child run
+-- also carries on its own `item` column — kept here too because this table,
+-- not the run, is what a parent's UI would actually join through to list
+-- "everything this step fanned out into."
+--
+-- One child never has two parents: `childRunId` is unique. A parent can have
+-- many children, which is the whole point.
+
+CREATE TABLE "workflow_run_edges" (
+  "id" varchar(25) PRIMARY KEY,
+  "parentRunId" varchar(25) NOT NULL,
+  "childRunId" varchar(25) NOT NULL,
+  "sourceStepKey" varchar(64),
+  "itemIndex" integer,
+  "itemKey" varchar(255),
+  "item" jsonb,
+  "isActive" boolean DEFAULT true,
+  "mtId1" varchar(25),
+  "mtId2" varchar(25),
+  "mtId3" varchar(25),
+  "mtId4" varchar(25),
+  "recordCreatedDate" timestamp,
+  "recordModifiedDate" timestamp,
+  "recordCreatedBy" varchar(25),
+  "recordModifiedBy" varchar(25)
+);
+
+CREATE INDEX "workflow_run_edges_parent_index" ON "workflow_run_edges" ("parentRunId");
+CREATE UNIQUE INDEX "workflow_run_edges_child_unique" ON "workflow_run_edges" ("childRunId");

package/migrations/0009_workflow_steps_layout.sql

@@ -0,0 +1,11 @@
+-- 0009_workflow_steps_layout.sql
+-- Canvas position is NOT execution order. `position` (0004) is an integer
+-- used to sequence steps when a step has no transitions of its own — insert
+-- one in the middle and every position below it shifts. Where a step sits on
+-- the builder's free-form canvas is a separate, purely visual concern: two
+-- steps can be dragged anywhere relative to each other without changing what
+-- runs after what. `layout` is { x, y } in canvas pixels; null until a step
+-- has been placed by hand, at which point the builder can lay new steps out
+-- automatically (e.g. left to right by `position`).
+
+ALTER TABLE "workflow_steps" ADD COLUMN "layout" jsonb;

package/migrations/0010_workflow_steps_sample_output.sql

@@ -0,0 +1,17 @@
+-- 0010_workflow_steps_sample_output.sql
+-- What this step is EXPECTED to return, as an example — never what it did
+-- return. Purely a builder concern, like `layout` (0009), and never read by
+-- workflowRunner: a real run's output lives on workflow_step_runs.
+--
+-- It exists because binding one step to another is otherwise done from memory.
+-- A later step's value binds to {steps.<key>.output.something} and a
+-- transition tests output.something, and until now nothing in the product
+-- could tell you what `something` is for a given action — you either ran the
+-- workflow and read the run record, or you guessed. Recording a sample lets
+-- the step editor offer the real field names in a picker, which is also what
+-- makes a mistyped binding catchable at build time rather than at run time.
+--
+-- Nullable, and null simply means the picker has nothing to offer for that
+-- step yet — every existing step keeps working untouched.
+
+ALTER TABLE "workflow_steps" ADD COLUMN "sampleOutput" jsonb;

package/migrations/0011_workflow_steps_params.sql

@@ -0,0 +1,27 @@
+-- 0011_workflow_steps_params.sql
+-- `params` — what this step needs the CALLER to supply when the run is
+-- started. Declared here, on the step, because the step is where you find out
+-- you need it: you are binding `{params.customerEmail}` into an email-send's
+-- `to` and there is no such parameter yet.
+--
+-- The workflow's run-start schema is the UNION of every step's declaration
+-- (see workflowRunner's collectParams), not a separate list somebody has to
+-- keep in step with these. That is the whole point of declaring it here —
+-- adding the requirement and adding the binding are one action, and deleting
+-- the step deletes the requirement with it rather than leaving a parameter
+-- the run still demands and nothing reads.
+--
+-- Same field shape as `workflows.params` and as an action's inputSchema:
+--   [{ name, type, required, default, description, order, sample? }]
+-- so the engine validates a run's params with the SAME @xeplr/schema-handler
+-- applySchema that validates a step's input against its action. One definition
+-- of what "required" means, at both levels of the product.
+--
+-- `sample` is the one addition, and it is never sent anywhere: it is what the
+-- builder's { } picker shows beside the name, so a list of parameters reads as
+-- something you can recognise rather than something you must already know.
+--
+-- Nullable, and null means "this step asks nothing of the caller" — which is
+-- every step that existed before this column did.
+
+ALTER TABLE "workflow_steps" ADD COLUMN IF NOT EXISTS "params" jsonb;

package/migrations/0012_workflows_kind.sql

@@ -0,0 +1,27 @@
+-- 0012_workflows_kind.sql
+-- WHAT A WORKFLOW'S STEPS ARE MADE OF — which is a question about the BUILDER,
+-- not about the engine.
+--
+-- Connecting jobs to each other opens the same canvas, saves the same rows and
+-- is driven by the same engine. The only difference is what the palette offers
+-- and what dropping something onto the canvas produces:
+--
+--   'workflow'   the action catalogue; a drop names an action
+--   'jobs'       the job list;         a drop becomes a `job-run` step whose
+--                                      values carry that job's id
+--
+-- workflowRunner NEVER READS THIS. A job step is an ordinary wait step whose
+-- action happens to call the jobs API, so teaching the engine about the
+-- distinction would buy nothing and would put a product concept ("a job") into
+-- the one file that has managed to stay ignorant of every product concept so
+-- far. If this column were dropped tomorrow every existing run would continue
+-- to behave identically.
+--
+-- A STRING, NOT A BOOLEAN, because the next one is already visible: the same
+-- canvas over saved API calls, and after that whatever else gets connected.
+-- `is_job_workflow` would have to be replaced the day that lands, and every
+-- row and query that referenced it with it.
+--
+-- Defaulted to 'workflow' so every workflow that exists today keeps opening
+-- the way it always has.
+ALTER TABLE workflows ADD COLUMN IF NOT EXISTS kind VARCHAR(32) NOT NULL DEFAULT 'workflow';

package/migrations/0013_workflows_key.sql

@@ -0,0 +1,48 @@
+-- 0013_workflows_key.sql
+-- `key` — HOW AN APP THAT IS NOT THIS ONE NAMES A WORKFLOW.
+--
+-- Added for kind = 'screens' (a "flow"): a workflow whose every step shows a
+-- screen to a person and waits for them to submit it. A flow is designed and
+-- run through the /flows facade (lib/flows.js) by a different app —
+-- the one that owns the screens — and that app knows its flows by names it
+-- chose ('onboard_employee'), not by ids minted here. Every /flows route is
+-- addressed by this key.
+--
+-- ── why 'screens' needs no column of its own ────────────────────────────
+--
+-- `workflows.kind` (0012) is already an unconstrained VARCHAR(32) with no
+-- CHECK and no enum type — it was written that way deliberately, because the
+-- next kind after 'jobs' was already visible. 'screens' is that next kind, so
+-- it lands with no DDL at all; the list of accepted values lives in the
+-- model's jsonSchema, where a bad value is refused with the field named rather
+-- than as a constraint violation.
+--
+-- The engine still never reads `kind` — a screen step is an ordinary wait step
+-- whose action happens to do nothing. What the value decides is WHO MAY EDIT
+-- THE ROW: the workflow document's own save route refuses a 'screens'
+-- workflow, because those steps are generated from a design held in the other
+-- app and a hand edit here would be silently overwritten by the next PUT
+-- /flows/:key. Reading and running are untouched, so runs and history stay
+-- visible in the builder.
+--
+-- ── the uniqueness rule ─────────────────────────────────────────────────
+--
+-- A key identifies a flow WITHIN A TENANT, not globally: two companies each
+-- having an 'onboard_employee' flow is the normal case, and making the key
+-- globally unique would let the first company to use a word take it from
+-- everyone. So the index is over the tenant slots plus the key.
+--
+-- COALESCE on the mt columns because Postgres treats NULLs as distinct in a
+-- unique index: an app that registered only one tenant level leaves mtId2
+-- null, and without this every row would look unique to the index and the
+-- duplicate it exists to prevent would be inserted happily.
+--
+-- Partial (WHERE "key" IS NOT NULL) because ordinary workflows and jobs
+-- canvases have no key and never will — they are found by id — and hundreds of
+-- null-keyed rows should not have to fit through this index.
+
+ALTER TABLE "workflows" ADD COLUMN IF NOT EXISTS "key" varchar(64);
+
+CREATE UNIQUE INDEX IF NOT EXISTS "workflows_key_unique"
+  ON "workflows" (COALESCE("mtId1", ''), COALESCE("mtId2", ''), "key")
+  WHERE "key" IS NOT NULL;

package/migrations-auth/0001_workflow_access.sql

@@ -0,0 +1,129 @@
+-- 0001_workflow_access.sql
+-- xeplr-workflow's AUTH-DB extension data — layered on top of auth's base
+-- migrations (runs after them: AUTH_EXT_MIGRATIONS_DIR). Adds this product's
+-- roles + menus, maps Super Admin to everything, and applies the default
+-- role→access matrix. All inserts are insert-if-absent (WHERE NOT EXISTS),
+-- safe to re-run against an already-seeded DB.
+--
+-- Its OWN auth database (AUTH_DB_NAME=xeplr_workflow_auth), not xeplr-bi's.
+-- Sharing one would mean a role granted in BI silently granting workflow
+-- pages, which is not a thing anybody would have decided on purpose.
+
+INSERT INTO "roles" (id, name, "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), name, true, '*', now(), now()
+FROM (VALUES ('Super Admin'), ('CompanyAdmin'), ('Creator'), ('Viewer')) AS v(name)
+WHERE NOT EXISTS (SELECT 1 FROM "roles" r WHERE r.name = v.name);
+
+-- The drawer reads these: a menu row named here shows up in the nav for any
+-- role mapped to it, and does not exist for a role that isn't.
+-- The drawer reads these: a menu row named here shows up in the nav for any
+-- role mapped to it, and does not exist for a role that isn't. Add the
+-- workflow pages' rows in a LATER migration alongside the pages themselves —
+-- seeding a menu for a page that does not exist yet puts a dead item in the
+-- rail for everyone.
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), name, "group", false, true, '*', now(), now()
+FROM (VALUES
+  ('Home', 'workflows:view'),
+  ('Actions', 'workflows:view'),
+  ('Configuration', 'configuration:view'),
+  ('Access Control', 'configuration:access:view')
+) AS v(name, "group")
+WHERE NOT EXISTS (SELECT 1 FROM "menus" m WHERE m.name = v.name);
+
+-- This product's own APIs. Every route in routes/index.js that should be
+-- gate-able gets a row here, grouped to match the menuGroup/apiGroup values
+-- the role matrix below already reads. `/public/resume/:key` is isPublic —
+-- it's never gated by role at all (a resume click isn't made by a signed-in
+-- user), so it's grouped for bookkeeping only, not for the matrix below to
+-- match against.
+INSERT INTO "apis" (id, name, "apiGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), name, "group", "public", true, '*', now(), now()
+FROM (VALUES
+  ('List workflows', 'workflows:view', false),
+  ('Get workflow', 'workflows:view', false),
+  ('List actions', 'workflows:view', false),
+  ('Save workflow', 'workflows:create', false),
+  ('Delete workflow', 'workflows:create', false),
+  ('Run workflow', 'workflows:run', false),
+  ('Resume workflow step', 'workflows:public', true)
+) AS v(name, "group", "public")
+WHERE NOT EXISTS (SELECT 1 FROM "apis" a WHERE a."apiGroup" = v."group" AND a.name = v.name);
+
+-- Super Admin → everything that now exists (base apis/pages/elements/menus +
+-- this product's menus).
+INSERT INTO "apisRolesMapping" (id, "roleId", "apiId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, a.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "apis" a
+WHERE r.name = 'Super Admin'
+  AND NOT EXISTS (SELECT 1 FROM "apisRolesMapping" m WHERE m."roleId" = r.id AND m."apiId" = a.id);
+
+INSERT INTO "uiPagesRolesMapping" (id, "roleId", "uiPageId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, p.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "uiPages" p
+WHERE r.name = 'Super Admin'
+  AND NOT EXISTS (SELECT 1 FROM "uiPagesRolesMapping" m WHERE m."roleId" = r.id AND m."uiPageId" = p.id);
+
+INSERT INTO "uiElementsRolesMapping" (id, "roleId", "uiElementId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, e.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "uiElements" e
+WHERE r.name = 'Super Admin'
+  AND NOT EXISTS (SELECT 1 FROM "uiElementsRolesMapping" m WHERE m."roleId" = r.id AND m."uiElementId" = e.id);
+
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Super Admin'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+-- Scoped-role default access matrix (global WHAT; per-company/workspace scope
+-- comes from userTenantsMapping, not from this).
+
+-- CompanyAdmin: workflows:* and configuration:* (prefix).
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'CompanyAdmin'
+  AND (m."menuGroup" LIKE 'workflows:%' OR m."menuGroup" LIKE 'configuration:%')
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+INSERT INTO "apisRolesMapping" (id, "roleId", "apiId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, a.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "apis" a
+WHERE r.name = 'CompanyAdmin'
+  AND (a."apiGroup" LIKE 'workflows:%' OR a."apiGroup" LIKE 'configuration:%')
+  AND NOT EXISTS (SELECT 1 FROM "apisRolesMapping" m WHERE m."roleId" = r.id AND m."apiId" = a.id);
+
+-- Creator: can see, build and run. Note that RUNNING is deliberately a
+-- creator's right and not a viewer's — a run has side effects (it sends mail,
+-- moves files, writes to databases), so "can look at it" must not imply "can
+-- fire it".
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Creator'
+  AND m."menuGroup" IN ('workflows:view', 'workflows:create', 'workflows:run')
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+INSERT INTO "apisRolesMapping" (id, "roleId", "apiId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, a.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "apis" a
+WHERE r.name = 'Creator'
+  AND a."apiGroup" IN ('workflows:view', 'workflows:create', 'workflows:run')
+  AND NOT EXISTS (SELECT 1 FROM "apisRolesMapping" m WHERE m."roleId" = r.id AND m."apiId" = a.id);
+
+-- Viewer: workflows:view (exact). Sees the workflows and their history; fires
+-- nothing.
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Viewer'
+  AND m."menuGroup" = 'workflows:view'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+INSERT INTO "apisRolesMapping" (id, "roleId", "apiId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, a.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "apis" a
+WHERE r.name = 'Viewer'
+  AND a."apiGroup" = 'workflows:view'
+  AND NOT EXISTS (SELECT 1 FROM "apisRolesMapping" m WHERE m."roleId" = r.id AND m."apiId" = a.id);

package/migrations-auth/0003_nav_menus.sql

@@ -0,0 +1,62 @@
+-- 0003_nav_menus.sql
+-- The rail's new items: Dashboards, Jobs, and the two scope pickers.
+--
+-- A SEPARATE MIGRATION rather than an edit to 0001, because 0001 has already
+-- run — the migrator records what it has applied and will not re-run a file
+-- whose contents changed. Editing it would seed nothing and leave the new items
+-- role-filtered out of everyone's drawer, which looks exactly like a
+-- permissions bug.
+--
+-- Seeded alongside the pages themselves, which is the rule 0001's comment
+-- states: a menu row for a page that does not exist puts a dead item in the
+-- rail for everyone. Dashboards and Jobs are placeholders today, but they are
+-- real routes that render a real page saying so — which is a different thing
+-- from a link that goes nowhere.
+--
+-- Every insert is insert-if-absent, safe to re-run.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), name, "group", false, true, '*', now(), now()
+FROM (VALUES
+  ('Dashboards', 'workflows:view'),
+  ('Jobs', 'workflows:view'),
+  -- The scope pickers are workflows:view rather than configuration:*. Choosing
+  -- which workspace you are looking at is not administering anything, and a
+  -- Viewer who cannot switch workspace is a Viewer locked into whichever one
+  -- they happened to land in.
+  ('Select Workspace', 'workflows:view'),
+  ('Select Company', 'workflows:view')
+) AS v(name, "group")
+WHERE NOT EXISTS (SELECT 1 FROM "menus" m WHERE m.name = v.name);
+
+-- Super Admin → everything, including whatever was just added.
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Super Admin'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+-- And the scoped roles, on the same matrix 0001 established: CompanyAdmin gets
+-- the workflows:* prefix, Creator and Viewer get exact groups. Re-run here so
+-- the new rows are covered — 0001's inserts only saw the menus that existed
+-- when it ran.
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'CompanyAdmin'
+  AND (m."menuGroup" LIKE 'workflows:%' OR m."menuGroup" LIKE 'configuration:%')
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Creator'
+  AND m."menuGroup" IN ('workflows:view', 'workflows:create', 'workflows:run')
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);
+
+INSERT INTO "menuRolesMapping" (id, "menuId", "roleId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), m.id, r.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Viewer'
+  AND m."menuGroup" = 'workflows:view'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);