@protobase/server 0.67.11 → 0.68.0

package/dist/workflows/schema-sql.js

@@ -1,6 +1,6 @@
 import { quoteIdent } from "../changes/capture-sql.js";
 /** The comment the schema's function carries, which the startup check reads. */
-const workflowsComment = `Protobase workflows 3`;
+const workflowsComment = `Protobase workflows 6`;
 const commentVersion = (comment) => {
 	const match = comment?.match(/^Protobase workflows (\d+)$/);
 	return match ? Number(match[1]) : void 0;
@@ -46,6 +46,7 @@ create table if not exists ${s}."runs" (
   "cause" text,
   "resume_at" timestamptz,
   "started_by" text,
+  "rerun_of" uuid references ${s}."runs" ("id") on delete set null,
   "tenant_id" text,
   "created_at" timestamptz not null default now(),
   "finished_at" timestamptz,
@@ -77,6 +78,61 @@ create table if not exists ${s}."steps" (
   unique ("run_id", "scope", "seq")
 )`;
 };
+/** The most bytes a trigger's cursor or store holds as JSON, so a plugin cannot grow them without limit. */
+const triggerStateBytes = 65536;
+/**
+* Which version of a workflow is on (`enabled_version`, null when off), and one row per trigger of an enabled version:
+* its type and input, and the state its kind keeps. A change raises `generation`, so a job queued for an older one
+* ends without acting. A trigger being stopped stays `stopping` until its stop job removes it. Written whole each time:
+* every statement is idempotent.
+*/
+const triggersSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `alter table ${s}."workflows" add column if not exists "enabled_version" integer;
+do $$ begin
+  if not exists (select 1 from pg_constraint where conname = 'workflows_enabled_version' and connamespace = ${`'${schema.replaceAll("'", "''")}'`}::regnamespace) then
+    alter table ${s}."workflows" add constraint "workflows_enabled_version" foreign key ("id", "enabled_version") references ${s}."versions" ("workflow_id", "version") deferrable initially deferred;
+  end if;
+end $$;
+create table if not exists ${s}."triggers" (
+  "id" uuid primary key default gen_random_uuid(),
+  "workflow_id" uuid not null references ${s}."workflows" ("id") on delete cascade,
+  "version" integer not null,
+  "tenant_id" text,
+  "type" text not null,
+  "input" jsonb not null,
+  "connection_id" text,
+  "status" text not null check ("status" in ('active', 'failing', 'needs_sign_in', 'stopping')),
+  "generation" integer not null,
+  "cursor" jsonb check (octet_length("cursor"::text) <= ${triggerStateBytes}),
+  "store" jsonb check (octet_length("store"::text) <= ${triggerStateBytes}),
+  "poll_job_id" text,
+  "consecutive_failures" integer not null,
+  "last_error" jsonb,
+  "next_poll_at" timestamptz,
+  "created_at" timestamptz not null default now(),
+  "updated_at" timestamptz not null default now()
+);
+create unique index if not exists "triggers_workflow" on ${s}."triggers" ("workflow_id") where "status" <> 'stopping';
+create index if not exists "triggers_workflow_id" on ${s}."triggers" ("workflow_id");
+create index if not exists "triggers_updated_at" on ${s}."triggers" ("updated_at");
+create index if not exists "triggers_status_type" on ${s}."triggers" ("status", "type");
+create index if not exists "triggers_connection" on ${s}."triggers" ("connection_id");
+create index if not exists "triggers_tenant" on ${s}."triggers" ("tenant_id")`;
+};
+/**
+* What a step that changes records kept under its idempotency key, written with its records, so a retry of the step
+* after they committed writes nothing and returns them. Its rows go with their run.
+*/
+const effectsSql = (schema) => {
+	const s = quoteIdent(schema);
+	return `create table if not exists ${s}."effects" (
+  "run_id" uuid not null references ${s}."runs" ("id") on delete cascade,
+  "key" text not null,
+  "result" jsonb,
+  primary key ("run_id", "key")
+)`;
+};
 /** An index for each filter and sort the API takes, and pg_trgm ones for the search over names. */
 const indexesSql = (schema) => {
 	const s = quoteIdent(schema);
@@ -88,6 +144,8 @@ create index if not exists "workflows_name_search" on ${s}."workflows" using gin
 create index if not exists "versions_tenant" on ${s}."versions" ("tenant_id");
 alter table ${s}."runs" add column if not exists "key" text;
 create unique index if not exists "runs_key" on ${s}."runs" ("workflow_id", "key");
+alter table ${s}."runs" add column if not exists "rerun_of" uuid references ${s}."runs" ("id") on delete set null;
+create index if not exists "runs_rerun_of" on ${s}."runs" ("rerun_of");
 create index if not exists "runs_workflow" on ${s}."runs" ("workflow_id", "created_at");
 create index if not exists "runs_tenant" on ${s}."runs" ("tenant_id");
 create index if not exists "runs_status" on ${s}."runs" ("status");
@@ -102,7 +160,7 @@ const workflowsTriggers = ["workflow_version", "run_version"];
 * A workflow numbers its next version as a save changes its definition, in the row the write returns, so its ETag is
 * the saved row's; the save hook keeps that version's definition and who saved it. A run takes its workflow's current
 * version as it is created, and refuses a workflow of another tenant as one that is not there, and one that has no
-* saved version.
+* saved version. A re-run takes the input of the run it re-runs, which the start hook checks.
 */
 const functionsSql = (schema) => {
 	const s = quoteIdent(schema);
@@ -115,6 +173,10 @@ begin
   end if;
   -- The write holds the row, so a save in another transaction numbers its version after this one.
   new.version := case when new.definition is distinct from old.definition then coalesce(old.version, 0) + 1 else old.version end;
+  -- An enabled workflow stays enabled on its new version; the save hook moves its trigger along.
+  if new.version is distinct from old.version and old.enabled_version is not null and new.enabled_version is not distinct from old.enabled_version then
+    new.enabled_version := new.version;
+  end if;
   new.updated_at := now();
   return new;
 end
@@ -135,7 +197,13 @@ begin
   if found.version is null then
     raise exception 'Workflow % has no saved version', new.workflow_id using errcode = '23503';
   end if;
-  new.version := found.version;
+  -- A trigger starts a run of the version that is enabled, which it gives; any other start runs the current one.
+  if new.version is null then
+    new.version := found.version;
+  end if;
+  if new.rerun_of is not null then
+    select r.input into new.input from ${s}."runs" r where r.id = new.rerun_of and r.workflow_id = new.workflow_id;
+  end if;
   return new;
 end
 $$;
@@ -144,4 +212,4 @@ drop trigger if exists "run_version" on ${s}."runs";
 create trigger "run_version" before insert on ${s}."runs" for each row execute function ${s}."run_version"()`;
 };
 //#endregion
-export { commentVersion, functionsSql, indexesSql, tablesSql, workflowsComment, workflowsTriggers };
+export { commentVersion, effectsSql, functionsSql, indexesSql, tablesSql, triggerStateBytes, triggersSql, workflowsComment, workflowsTriggers };

package/dist/workflows/schema.d.ts

@@ -5,7 +5,7 @@ import { Db } from "@protobase/query";
  * The SQL that brings the `workflows` schema to what `workflows` needs: its tables, indexes and the triggers that number a
  * workflow's versions and pin a run's; `undefined` when current. Tables are never dropped.
  */
-export declare const workflowsMigration: (db: Db, options?: WorkflowsOptions) => Promise<string | undefined>;
+export declare const workflowsMigration: (db: Db, options?: Pick<WorkflowsOptions, "schema">) => Promise<string | undefined>;
 /** Refuses to go on while the `workflows` schema lacks what `workflows` needs; the project's migrations add it. */
-export declare const checkWorkflowsSchema: (db: Db, options?: WorkflowsOptions) => Promise<void>;
+export declare const checkWorkflowsSchema: (db: Db, options?: Pick<WorkflowsOptions, "schema">) => Promise<void>;
 //#endregion

package/dist/workflows/schema.js

@@ -1,19 +1,21 @@
 import { quoteIdent } from "../changes/capture-sql.js";
 import { migrationCommand } from "../changes/capture-schema.js";
 import { workflowsSchema } from "./options.js";
-import { commentVersion, functionsSql, indexesSql, tablesSql, workflowsTriggers } from "./schema-sql.js";
+import { commentVersion, effectsSql, functionsSql, indexesSql, tablesSql, triggersSql, workflowsTriggers } from "./schema-sql.js";
 import { sql } from "kysely";
 //#region src/workflows/schema.ts
 const readWorkflowsSchema = async (db, schema) => {
 	const steps = `${quoteIdent(schema)}."steps"`;
+	const triggerRows = `${quoteIdent(schema)}."triggers"`;
 	const { rows } = await sql`select to_regclass(${steps}) is not null as found,
+    to_regclass(${triggerRows}) is not null as trigger_rows,
     (select obj_description(p.oid, 'pg_proc') from pg_proc p join pg_namespace n on n.oid = p.pronamespace where n.nspname = ${schema} and p.proname = 'run_version') as comment,
     (select count(*)::int from pg_trigger t join pg_class c on c.oid = t.tgrelid join pg_namespace n on n.oid = c.relnamespace
       where n.nspname = ${schema} and not t.tgisinternal and t.tgname = any(${workflowsTriggers})) as triggers`.execute(db);
 	const row = rows[0];
 	return {
 		tables: row.found,
-		current: row.found && commentVersion(row.comment) === 3 && row.triggers === workflowsTriggers.length
+		current: row.found && row.trigger_rows && commentVersion(row.comment) === 6 && row.triggers === workflowsTriggers.length
 	};
 };
 /**
@@ -27,6 +29,8 @@ const workflowsMigration = async (db, options = {}) => {
 	return `${[
 		`create schema if not exists ${quoteIdent(schema)}`,
 		...found.tables ? [] : [tablesSql(schema)],
+		triggersSql(schema),
+		effectsSql(schema),
 		indexesSql(schema),
 		functionsSql(schema)
 	].join(";\n\n")};`;

package/dist/workflows/start-hook.js

@@ -3,13 +3,15 @@ import { requestAccess, requireOperation } from "../request-access.js";
 import { deletedRows } from "../params.js";
 import { fetchReadable } from "../fetch-readable.js";
 import { checkRunInput } from "./input-limits.js";
+import { keepEarlierSteps } from "./rerun.js";
 //#region src/workflows/start-hook.ts
 /**
 * Starts a run as it is created through the API, in the write's transaction: it refuses an input over its limits and
-* a workflow the caller cannot read in their tenant (404, as the API answers for it), and queues the run's first
-* segment, which runs once the write commits. The resource records who started it, as the run's author.
+* a workflow the caller cannot read in their tenant (404, as the API answers for it), takes a re-run up after the steps
+* it keeps of the run it re-runs, and queues the run's first segment, which runs once the write commits. The resource
+* records who started it, as the run's author.
 */
-const runStartHook = (runner, deps) => async (event, trx) => {
+const runStartHook = (runner, deps, schema) => async (event, trx) => {
 	if (event.resource.name !== "workflow_runs" || event.operation !== "create" || !event.after) return;
 	checkRunInput(event.after.input);
 	const entry = deps().registry.find("workflows");
@@ -20,6 +22,10 @@ const runStartHook = (runner, deps) => async (event, trx) => {
 	requireOperation(access, "read");
 	const key = access.full.fields[access.full.primaryKey[0]];
 	if (!await fetchReadable(trx, access, [String(event.after.workflow_id)], deletedRows(access.full, false), { fields: [key] })) throw notFound(`No ${entry.name} with this key`);
+	if (event.after.rerun_of) await keepEarlierSteps(trx, deps(), schema, {
+		...event,
+		after: event.after
+	});
 	await runner.start(trx, String(event.after.id));
 };
 //#endregion

package/dist/workflows/start-workflow.d.ts

@@ -17,10 +17,12 @@ export type StartWorkflowOptions = {
   key?: string;
   /** The schema of `workflows`, when the config names another. Default `workflows`. */
   schema?: string;
+  /** The version to run, as a trigger runs the enabled one; default the workflow's current version. */
+  version?: number;
 };
 /**
  * Starts a run of a workflow from the app's own code, such as a job or a write hook, and returns the run's id. In
  * `db`'s own transaction when it is one, so the run starts when the caller's writes commit, or not at all.
  */
-export declare const startWorkflow: (db: Db, { workflow, input, tenant, startedBy, key, schema }: StartWorkflowOptions) => Promise<string>;
+export declare const startWorkflow: (db: Db, { workflow, input, tenant, startedBy, key, schema, version }: StartWorkflowOptions) => Promise<string>;
 //#endregion

package/dist/workflows/start-workflow.js

@@ -7,13 +7,13 @@ import { sql } from "kysely";
 * Starts a run of a workflow from the app's own code, such as a job or a write hook, and returns the run's id. In
 * `db`'s own transaction when it is one, so the run starts when the caller's writes commit, or not at all.
 */
-const startWorkflow = async (db, { workflow, input, tenant, startedBy, key, schema = "workflows" }) => {
+const startWorkflow = async (db, { workflow, input, tenant, startedBy, key, schema = "workflows", version }) => {
 	checkRunInput(input);
 	const job = currentJobs().definition(segmentJobName);
 	if (!job) throw new Error("Workflows are not running in this app: add `workflows: {}` to protobase.config.ts");
 	const runs = sql.id(schema, "runs");
-	const { rows } = await sql`insert into ${runs} (workflow_id, input, tenant_id, started_by, key)
-    values (${workflow}, ${input === void 0 ? null : JSON.stringify(input)}::jsonb, ${tenant === void 0 ? null : String(tenant)}, ${startedBy ?? null}, ${key ?? null})
+	const { rows } = await sql`insert into ${runs} (workflow_id, version, input, tenant_id, started_by, key)
+    values (${workflow}, ${version ?? null}, ${input === void 0 ? null : JSON.stringify(input)}::jsonb, ${tenant === void 0 ? null : String(tenant)}, ${startedBy ?? null}, ${key ?? null})
     on conflict (workflow_id, key) do nothing returning id`.execute(db);
 	if (rows.length === 0) {
 		const existing = (await sql`select id, status from ${runs} where workflow_id = ${workflow} and key = ${key}`.execute(db)).rows[0];

package/dist/workflows/triggers/trigger-jobs.js

@@ -0,0 +1,114 @@
+import { defineJob } from "../../jobs/define-job.js";
+import { readyAt, readyWhen, resolveTimeTerms } from "../ready/ready-when.js";
+import { activeTriggers, currentTrigger, triggerFailed } from "./trigger-row.js";
+import { orRefusal, readyContext, startIfReady } from "../ready/ready-start.js";
+import { encodeKey } from "@protobase/schema/internal";
+import { printFilter } from "@protobase/schema";
+import { sql } from "kysely";
+//#region src/workflows/triggers/trigger-jobs.ts
+/** Records one enable pass reads per job. */
+const passSize = 100;
+/**
+* The jobs that run triggers on every server process, so turning a workflow on, changing or turning it off needs no
+* restart: `workflows.trigger-start` (for a ready trigger, one pass over the records that already match, 100 per job),
+* `workflows.trigger-stop` (removes a stopped trigger), and `workflows.ready-check` (starts a run of one record when it
+* is ready, at the time its time terms say). Each acts only on the generation it was queued for.
+*/
+const triggerJobs = (input) => {
+	const { schema } = input;
+	const readyCheck = defineJob({
+		name: "workflows.ready-check",
+		timeout: "5 minutes",
+		run: async ({ trigger: id, generation, key }, { db }) => {
+			const trigger = await currentTrigger(db, schema, id, generation);
+			if (!trigger) return;
+			if (await startIfReady(input, db, trigger, key)) await start.enqueue(db, {
+				trigger: id,
+				generation
+			});
+		}
+	});
+	const queueCheck = async (db, trigger, primaryKey, timeTerms, record) => {
+		const at = readyAt(timeTerms, record, /* @__PURE__ */ new Date());
+		if (!at) return;
+		const key = Object.fromEntries(primaryKey.map((name) => [name, record[name]]));
+		const recordKey = encodeKey(primaryKey.map((name) => record[name]));
+		await readyCheck.enqueue(db, {
+			trigger: trigger.id,
+			generation: trigger.generation,
+			key
+		}, {
+			runAt: at,
+			key: `ready:${trigger.id}:${trigger.generation}:${recordKey}:${at.toISOString()}`
+		});
+	};
+	const start = defineJob({
+		name: "workflows.trigger-start",
+		timeout: "5 minutes",
+		run: async ({ trigger: id, generation, page_token }, { db }) => {
+			const trigger = await currentTrigger(db, schema, id, generation);
+			if (!trigger || !input.declared(trigger.type)) return;
+			const found = await orRefusal(readyContext(input, trigger));
+			if ("refused" in found) return triggerFailed(db, schema, trigger, "refused", found.refused);
+			if (!found.value) return;
+			const { spec, model, records } = found.value;
+			const split = readyWhen(spec.when);
+			if (!split.ok) return;
+			const filter = split.when.filter && printFilter(split.when.filter);
+			const listed = await orRefusal(records.list(spec.resource, {
+				...filter && { filter },
+				page_size: passSize,
+				...page_token && { page_token }
+			}));
+			if ("refused" in listed) return triggerFailed(db, schema, trigger, "refused", listed.refused);
+			const page = listed.value;
+			const timeTerms = resolveTimeTerms(model, split.when.timeTerms);
+			for (const record of page.items) await queueCheck(db, trigger, model.primaryKey, timeTerms, record);
+			if (page.next_page_token) await start.enqueue(db, {
+				trigger: id,
+				generation,
+				page_token: page.next_page_token
+			});
+		}
+	});
+	const stop = defineJob({
+		name: "workflows.trigger-stop",
+		run: async ({ trigger }, { db }) => {
+			await sql`delete from ${sql.id(schema, "triggers")} where id = ${trigger} and status = 'stopping'`.execute(db);
+		}
+	});
+	/**
+	* Routes each dispatched change to the ready triggers on its resource and tenant: it queues the check of the record at
+	* the time it becomes ready, in the dispatch's transaction. No sweep runs: a record becomes ready by a write, or at a
+	* time a write set.
+	*/
+	const onChanges = async (db, changes) => {
+		const types = [...input.readyTypes];
+		if (types.length === 0) return;
+		const triggers = await activeTriggers(db, schema, types);
+		for (const trigger of triggers) {
+			const spec = input.declared(trigger.type)?.ready(trigger.input);
+			const model = spec && input.deps().registry.find(spec.resource)?.model;
+			const split = spec && readyWhen(spec.when);
+			if (!spec || !model || !split?.ok) continue;
+			const timeTerms = resolveTimeTerms(model, split.when.timeTerms);
+			for (const change of changes) {
+				if (change.resource !== spec.resource || !change.after) continue;
+				if (String(change.tenant ?? "") !== String(trigger.tenant_id ?? "")) continue;
+				await queueCheck(db, trigger, model.primaryKey, timeTerms, change.after);
+			}
+		}
+	};
+	return {
+		jobs: [
+			start,
+			stop,
+			readyCheck
+		],
+		start,
+		stop,
+		onChanges
+	};
+};
+//#endregion
+export { triggerJobs };

package/dist/workflows/triggers/trigger-row.js

@@ -0,0 +1,36 @@
+import { sql } from "kysely";
+//#region src/workflows/triggers/trigger-row.ts
+/**
+* The trigger with this id while it is running on this generation, with who saved its version: `undefined` once it
+* was changed, stopped or removed, so a job queued for it before then does nothing.
+*/
+const currentTrigger = async (db, schema, id, generation) => {
+	const { rows } = await sql`select t.id, t.workflow_id, t.version, t.tenant_id, t.type, t.input, t.generation, t.status, v.saved_by
+    from ${sql.id(schema, "triggers")} t join ${sql.id(schema, "versions")} v on v.workflow_id = t.workflow_id and v.version = t.version
+    where t.id = ${id} and t.generation = ${generation} and t.status in ('active', 'failing')`.execute(db);
+	return rows[0];
+};
+/**
+* The running triggers of these types, failing ones included so a write can show they work again; each dispatch of
+* changes reads them, and the `(status, type)` index serves it.
+*/
+const activeTriggers = async (db, schema, types) => (await sql`select id, workflow_id, version, tenant_id, type, input, generation, status from ${sql.id(schema, "triggers")}
+    where status in ('active', 'failing') and type = any(${types})`.execute(db)).rows;
+/** Marks a trigger failing with an error its owner sees; the message names no secret. */
+const triggerFailed = async (db, schema, { id, generation, version }, code, message) => {
+	await sql`update ${sql.id(schema, "triggers")} set status = 'failing', consecutive_failures = consecutive_failures + 1,
+    last_error = ${JSON.stringify({
+		code,
+		message,
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	})}::jsonb, updated_at = now()
+    where id = ${id} and generation = ${generation} and version = ${version}`.execute(db);
+};
+/** Marks a failing trigger active again once it read a record; whether this call was the one that did. */
+const triggerRecovered = async (db, schema, { id, generation, version }) => {
+	const { rows } = await sql`update ${sql.id(schema, "triggers")} set status = 'active', consecutive_failures = 0, last_error = null, updated_at = now()
+    where id = ${id} and generation = ${generation} and version = ${version} and status = 'failing' returning id`.execute(db);
+	return rows.length > 0;
+};
+//#endregion
+export { activeTriggers, currentTrigger, triggerFailed, triggerRecovered };

package/dist/workflows/triggers/trigger-sync.js

@@ -0,0 +1,48 @@
+import { badRequest } from "../../problem.js";
+import { sql } from "kysely";
+//#region src/workflows/triggers/trigger-sync.ts
+const triggerOf = (definition) => {
+	const [type, input] = Object.entries(definition.trigger)[0];
+	return type === "manual" ? void 0 : {
+		type,
+		input
+	};
+};
+/**
+* Keeps a workflow's trigger row in step with its enabled version, in the write's transaction, queueing its jobs in that
+* same write: turning it on inserts a running trigger and queues its start; a new version with the same type and input
+* keeps the row, so its state carries over, and passes over the records again; any other change, or turning it off, stops the old row and starts a new one.
+* Only the current version can be turned on.
+*/
+const syncTrigger = async (trx, schema, jobs, workflow) => {
+	const enabled = workflow.enabled_version;
+	if (enabled !== null && enabled !== workflow.version) throw badRequest("invalid-workflow", `Only the current version can be enabled: set enabled_version to ${String(workflow.version)}, or clear it to turn the workflow off`);
+	const wanted = enabled === null ? void 0 : triggerOf(workflow.definition);
+	const triggers = sql.id(schema, "triggers");
+	const id = String(workflow.id);
+	const { rows } = await sql`select id, generation, version, (type = ${wanted?.type ?? null} and input = ${JSON.stringify(wanted?.input ?? null)}::jsonb and connection_id is null) as same
+    from ${triggers} where workflow_id = ${id} and status <> 'stopping'`.execute(trx);
+	const existing = rows[0];
+	if (existing?.same) {
+		if (existing.version === enabled) return;
+		await sql`update ${triggers} set version = ${enabled}, status = 'active', consecutive_failures = 0, last_error = null, updated_at = now() where id = ${existing.id}`.execute(trx);
+		await jobs.start.enqueue(trx, {
+			trigger: existing.id,
+			generation: existing.generation
+		});
+		return;
+	}
+	if (existing) {
+		await sql`update ${triggers} set status = 'stopping', generation = generation + 1, updated_at = now() where id = ${existing.id}`.execute(trx);
+		await jobs.stop.enqueue(trx, { trigger: existing.id });
+	}
+	if (!wanted) return;
+	const trigger = (await sql`insert into ${triggers} (workflow_id, version, tenant_id, type, input, status, generation, consecutive_failures)
+    values (${id}, ${enabled}, ${workflow.tenant_id ?? null}, ${wanted.type}, ${JSON.stringify(wanted.input)}::jsonb, 'active', 1, 0) returning id`.execute(trx)).rows[0].id;
+	await jobs.start.enqueue(trx, {
+		trigger,
+		generation: 1
+	}, { key: `trigger:${trigger}` });
+};
+//#endregion
+export { syncTrigger };

package/dist/workflows/workflow-engine.js

@@ -1,14 +1,16 @@
-import { stepTypeNames, stepTypes } from "./step-types.js";
 import { betterAuthOwnerRoles } from "../webhooks/table/owner-roles.js";
 import { runInputCheck } from "./input-limits.js";
 import { workflowSecrets, workflowsSchema } from "./options.js";
 import { workflowSaveHook } from "./save-hook.js";
 import { workflowsRunner } from "./segment-job.js";
 import { runStartHook } from "./start-hook.js";
+import { triggerJobs } from "./triggers/trigger-jobs.js";
+import { workflowTypes } from "./workflow-types.js";
 //#region src/workflows/workflow-engine.ts
 /**
 * What `createAdmin` needs for `workflows`: the hooks that check saves and start runs, the check of a run's input before
-* it is validated, and the segment job, whose step
+* it is validated, the app's trigger and step types, the segment and trigger jobs, the routing of changes to
+* ready triggers, and the segment job, whose step
 * types act on records as each workflow's last editor (from Better Auth unless the options say otherwise).
 */
 const workflowEngine = (options, deps, auth) => {
@@ -22,15 +24,25 @@ const workflowEngine = (options, deps, auth) => {
 		allowPrivateAddresses: Boolean(options.allowPrivateAddresses)
 	};
 	const secrets = workflowSecrets(options, globalThis.process?.env ?? {});
+	const types = workflowTypes(options.plugins, (name) => deps().registry.find(name)?.model);
 	const { runner, job } = workflowsRunner({
 		schema,
-		tasks: (context) => stepTypes(input, context.mail),
+		tasks: (context) => types.tasks(input, context.mail),
 		secrets
 	});
+	const triggers = triggerJobs({
+		deps,
+		schema,
+		roles,
+		declared: (type) => types.ready.get(type),
+		readyTypes: [...types.ready.keys()].filter((id) => types.check.triggers[id] !== void 0)
+	});
 	return {
-		hooks: [workflowSaveHook(schema, stepTypeNames), runStartHook(runner, deps)],
+		hooks: [workflowSaveHook(schema, types.check, triggers), runStartHook(runner, deps, schema)],
 		writeChecks: [runInputCheck],
-		job
+		jobs: [job, ...triggers.jobs],
+		onChanges: triggers.onChanges,
+		types
 	};
 };
 //#endregion

package/dist/workflows/workflow-types-route.js

@@ -0,0 +1,22 @@
+import { requestAccess, requireOperation } from "../request-access.js";
+import { Hono } from "hono";
+import { typeCatalog } from "@protobase/workflows";
+//#region src/workflows/workflow-types-route.ts
+/**
+* The app's trigger and step types, `GET /` at `workflowTypesPath`, as `list_workflow_types` lists them: the editor
+* draws its menus, forms and check from them. Only for a caller who may read the app's workflows, refused as reading a
+* workflow is.
+*/
+const workflowTypesRoute = (deps, types) => {
+	const catalog = typeCatalog(types);
+	const app = new Hono();
+	app.get("/", async (c) => {
+		const entry = deps.registry.find("workflows");
+		if (!entry) throw new Error("The workflow types are served only in an app with workflows");
+		requireOperation(await requestAccess(deps, entry, c.get("session")), "read");
+		return c.json(catalog);
+	});
+	return app;
+};
+//#endregion
+export { workflowTypesRoute };

package/dist/workflows/workflow-types.d.ts

@@ -0,0 +1,22 @@
+import { Mailer } from "../mail/mail-message.js";
+import { ServicesInput } from "./plugin-services.js";
+import { ResourceModel } from "@protobase/schema";
+import { CheckOptions, LoadedPlugin, TaskHandlers } from "@protobase/workflows";
+import { Plugin, ReadyTrigger } from "@protobase/workflows/plugin";
+//#region src/workflows/workflow-types.d.ts
+type Models = (name: string) => ResourceModel | undefined;
+/**
+ * The trigger and step types of an app: the built-in plugin, `app`, then the app's own, all through the same loader and
+ * interface. `types` is the list the MCP tools and the editor read; `check` is what a save checks a definition against,
+ * the available types only, and `checkWith` the same check against other resources, such as those a caller may read.
+ */
+export declare const workflowTypes: (loaded?: readonly LoadedPlugin[], models?: Models) => {
+  plugins: Plugin[];
+  types: import("@protobase/workflows").TypeEntry[];
+  check: CheckOptions;
+  checkWith: (against: Models) => CheckOptions;
+  tasks: (input: ServicesInput, mail: Mailer | undefined) => TaskHandlers;
+  ready: Map<string, ReadyTrigger>;
+};
+export type WorkflowTypes = ReturnType<typeof workflowTypes>;
+//#endregion

package/dist/workflows/workflow-types.js

@@ -0,0 +1,63 @@
+import { pluginServices } from "./plugin-services.js";
+import { readyProblems } from "./ready/ready-check.js";
+import { loadPlugins, stepHandlers, triggerChecks, typeList } from "@protobase/workflows";
+import { ConnectionError } from "@protobase/workflows/plugin";
+import { appPlugin } from "@protobase/workflow-plugins";
+//#region src/workflows/workflow-types.ts
+const unavailable = (type) => {
+	if (type.connection) return "It signs in through a connection, which this app cannot make yet";
+	if (type.kind === "polling" || type.kind === "webhook") return `This app does not run ${type.kind} triggers yet`;
+};
+const noConnection = (stepId, name) => ({ accessToken: () => Promise.reject(new ConnectionError("not_connected", `${stepId} signs in through "${name}", and this workflow has no sign-in for it`)) });
+const requiredInputs = (input) => Array.isArray(input.required) ? input.required : [];
+/** The ready triggers of `plugins`, by id. */
+const readyTriggers = (plugins) => new Map(plugins.flatMap((plugin) => Object.entries(plugin.triggers ?? {}).flatMap(([key, type]) => type.kind === "ready" ? [[`${plugin.name}:${key}`, type]] : [])));
+/**
+* The trigger and step types of an app: the built-in plugin, `app`, then the app's own, all through the same loader and
+* interface. `types` is the list the MCP tools and the editor read; `check` is what a save checks a definition against,
+* the available types only, and `checkWith` the same check against other resources, such as those a caller may read.
+*/
+const workflowTypes = (loaded = [], models = () => void 0) => {
+	const plugins = loadPlugins([{
+		plugin: appPlugin,
+		source: "@protobase/workflow-plugins"
+	}, ...loaded]);
+	const types = typeList(plugins, unavailable);
+	const available = new Set(types.filter((type) => type.kind !== "step" && type.available).map((type) => type.id));
+	const ready = readyTriggers(plugins);
+	const steps = types.filter((type) => type.kind === "step" && type.available);
+	const reasons = Object.fromEntries(types.flatMap((type) => type.reason === void 0 ? [] : [[type.id, type.reason]]));
+	const own = triggerChecks(plugins);
+	const checkWith = (against) => {
+		const checks = Object.entries(own).map(([id, check]) => {
+			const declared = ready.get(id);
+			if (!declared) return [id, check];
+			return [id, (input) => {
+				const problems = check(input);
+				return problems.length > 0 ? problems : readyProblems(against, declared.ready(input));
+			}];
+		});
+		return {
+			resources: steps.map((type) => type.id),
+			required: Object.fromEntries(steps.map((type) => [type.id, requiredInputs(type.input)])),
+			triggers: Object.fromEntries(checks.filter(([id]) => available.has(id))),
+			unavailable: reasons
+		};
+	};
+	const check = checkWith(models);
+	/** The step types of one segment, which sends mail with the mailer of the job that runs it. */
+	const tasks = (input, mail) => stepHandlers(plugins, {
+		services: pluginServices(input, mail),
+		connection: noConnection
+	});
+	return {
+		plugins,
+		types,
+		check,
+		checkWith,
+		tasks,
+		ready
+	};
+};
+//#endregion
+export { readyTriggers, workflowTypes };