@protobase/server 0.67.12 → 0.68.0

package/dist/workflows/plugin-records.js

@@ -0,0 +1,120 @@
+import { HttpProblem } from "../problem.js";
+import { tenantScope } from "../tenant.js";
+import { issueTicket } from "../files/ticket.js";
+import { runBatch } from "../batch/run-batch.js";
+import { assistantRecords, toolEntry } from "../assistant/records.js";
+import { effectsStore } from "./effects-store.js";
+import { runFileRef } from "./run-files.js";
+import { sql } from "kysely";
+import { StepError } from "@protobase/workflows";
+//#region src/workflows/plugin-records.ts
+const ticketSeconds = 60;
+/**
+* The session of the user who saved a version, with the roles they hold now in its tenant, so a workflow never does
+* more than its last editor may do today.
+*/
+const saverSession = async (roles, savedBy, tenant) => {
+	if (!savedBy) throw new StepError("Records.Refused", "The run's version was not saved by a user, so its steps act on no records");
+	const held = await roles({
+		id: savedBy,
+		...tenant !== void 0 && { tenant }
+	});
+	if (held.length === 0) throw new StepError("Records.Refused", "The workflow's last editor holds no role here any more, so its steps act on no records");
+	return {
+		user: {
+			id: savedBy,
+			roles: held
+		},
+		...tenant !== void 0 && {
+			tenant,
+			organization: { id: tenant }
+		}
+	};
+};
+/** The session a run's records steps act in: that of the user who saved the version the run pinned, in the run's tenant. */
+const runSession = async ({ deps, schema, roles }, runId) => {
+	const { rows } = await sql`select v.saved_by, r.tenant_id from ${sql.id(schema, "runs")} r
+    join ${sql.id(schema, "versions")} v on v.workflow_id = r.workflow_id and v.version = r.version where r.id = ${runId}`.execute(deps().db);
+	return saverSession(roles, rows[0]?.saved_by ?? null, rows[0]?.tenant_id ?? void 0);
+};
+const withTickets = async (deps, session, resource, data, runId) => {
+	const entry = toolEntry(deps, resource);
+	const result = { ...data };
+	for (const [name, value] of Object.entries(data)) {
+		const field = entry.model.fields[name];
+		if (field?.type === "decimal" && typeof value === "number") result[name] = String(value);
+		if (!field?.file || value === null || typeof value !== "object") continue;
+		if (!deps.files) throw new StepError("States.TaskFailed", "The app keeps no files");
+		const ref = runFileRef(runId, value, `data.${name}`);
+		const scope = {
+			tenant: String(tenantScope(entry, session)?.tenantValue ?? ""),
+			resource: entry.name,
+			field: name,
+			user: String(session.user.id)
+		};
+		result[name] = await issueTicket(deps.files.signer, {
+			provider: ref.provider,
+			path: ref.path,
+			name: ref.name,
+			...ref.size !== void 0 && { size: ref.size }
+		}, {}, scope, Math.floor(Date.now() / 1e3) + ticketSeconds);
+	}
+	return result;
+};
+const refusedAs = (error) => {
+	if (error instanceof HttpProblem) throw new StepError("Records.Refused", `${error.status} ${error.title}: ${error.detail}`);
+	throw error;
+};
+/**
+* The plugin context's `records` for one try of a step: the app's API as the user who saved the version the run runs, so
+* its access rules, tenant scope, validation and write hooks apply as they do to that user's own requests. A file value
+* of the run's own in a file field is written as the upload ticket the write takes. Each create keeps the step's
+* idempotency key and its place among the step's creates with its records, so a retry of the step after they committed,
+* such as after a crash before the step was saved, creates none again and returns them.
+*/
+const pluginRecords = (input, runId, idempotencyKey) => {
+	const open = async () => {
+		const deps = input.deps();
+		const session = await runSession(input, runId);
+		return {
+			deps,
+			session,
+			records: assistantRecords(deps, session)
+		};
+	};
+	const guarded = (work) => work().catch(refusedAs);
+	let creates = 0;
+	const createAll = async (resource, data) => {
+		const key = `${idempotencyKey}:${creates++}`;
+		const deps = input.deps();
+		const session = await runSession(input, runId);
+		const operations = [];
+		for (const item of data) operations.push({
+			op: "create",
+			resource,
+			data: await withTickets(deps, session, resource, item, runId)
+		});
+		return (await runBatch(deps, session, operations, {
+			key,
+			store: effectsStore(input.schema, runId)
+		})).flatMap((result) => result.op === "create" ? [result.record] : []);
+	};
+	return {
+		create: (resource, data) => guarded(async () => (await createAll(resource, [data]))[0]),
+		createMany: (resource, data) => guarded(() => createAll(resource, data)),
+		update: (resource, key, data) => guarded(async () => {
+			const { deps, session, records } = await open();
+			return (await records.update(resource, key, await withTickets(deps, session, resource, data, runId))).record;
+		}),
+		get: (resource, key) => guarded(async () => (await (await open()).records.get(resource, key)).record),
+		list: (resource, query) => guarded(async () => {
+			return (await (await open()).records.list(resource, {
+				...query.filter !== void 0 && { filter: query.filter },
+				...query.order_by !== void 0 && { order_by: query.order_by },
+				...query.limit !== void 0 && { page_size: query.limit }
+			})).items.map(({ etag: _, permissions: __, ...record }) => record);
+		})
+	};
+};
+//#endregion
+export { pluginRecords, saverSession };

package/dist/workflows/plugin-services.d.ts

@@ -0,0 +1,13 @@
+import "../files/runtime.js";
+import { Deps } from "../deps.js";
+import { SaverRoles } from "./plugin-records.js";
+import "@protobase/workflows";
+import "@protobase/workflows/plugin";
+//#region src/workflows/plugin-services.d.ts
+export type ServicesInput = {
+  deps: () => Deps;
+  schema: string;
+  roles: SaverRoles;
+  allowPrivateAddresses: boolean;
+};
+//#endregion

package/dist/workflows/plugin-services.js

@@ -0,0 +1,32 @@
+import { readRunFile, storeRunFile } from "./run-files.js";
+import { pluginRecords } from "./plugin-records.js";
+import { pluginFetch } from "./plugin-fetch.js";
+//#region src/workflows/plugin-services.ts
+/** The plugin context's `files`: those of the run alone, in the app's `private` file provider. */
+const runFiles = (files, runId) => ({
+	keep: (bytes, name, type) => storeRunFile(files(), runId, bytes, name, type),
+	read: async (value, field) => {
+		const { ref, bytes } = await readRunFile(files(), runId, value, field);
+		return {
+			name: ref.name,
+			...ref.type && { type: ref.type },
+			bytes
+		};
+	}
+});
+/** What the app gives a plugin's step in a run: the guarded fetch, records as the saver, the run's files and the mailer. */
+const pluginServices = ({ deps, schema, roles, allowPrivateAddresses }, mail) => {
+	const fetch = pluginFetch({ allowPrivateAddresses });
+	return (task) => ({
+		fetch,
+		records: pluginRecords({
+			deps,
+			schema,
+			roles
+		}, task.runId, task.idempotencyKey),
+		files: runFiles(() => deps().files, task.runId),
+		mail
+	});
+};
+//#endregion
+export { pluginServices, runFiles };

package/dist/workflows/ready/ready-check.js

@@ -0,0 +1,62 @@
+import { isCaptured } from "../../changes/capture-sql.js";
+import { readyWhen, timeField } from "./ready-when.js";
+import { checkFilter, parseFilter } from "@protobase/schema";
+//#region src/workflows/ready/ready-check.ts
+const timeTypes = /* @__PURE__ */ new Set(["timestamp", "date"]);
+const usesSearch = (node) => {
+	if (typeof node !== "object" || node === null) return false;
+	const kind = node.kind;
+	if (kind === "search" || kind === "similar") return true;
+	return Object.values(node).some(usesSearch);
+};
+/**
+* Why a ready trigger cannot run on the app's resources, checked as a workflow is saved: a resource that records no
+* changes (so no write reaches the trigger), a `when` that does not check against it (a field that is not indexed for
+* filtering among them, as for list filters), `now()` outside a time term, and key fields it does not have.
+*/
+const readyProblems = (models, spec) => {
+	const model = models(spec.resource);
+	if (!model) return [{
+		field: "resource",
+		message: `"${spec.resource}" is not a resource of this app`
+	}];
+	const problems = [];
+	if (!isCaptured(model)) problems.push({
+		field: "resource",
+		message: `${spec.resource} records no changes, so no write reaches a trigger: declare events on it`
+	});
+	for (const name of spec.key ?? []) {
+		const field = model.fields[name];
+		if (!field) problems.push({
+			field: "key",
+			message: `${spec.resource} has no field "${name}"`
+		});
+		else if (field.sensitive) problems.push({
+			field: "key",
+			message: `${name} is sensitive, so a record read never carries it`
+		});
+	}
+	if (spec.when === void 0) return problems;
+	const split = readyWhen(spec.when);
+	if (!split.ok) return [...problems, ...split.problems.map((message) => ({
+		field: "when",
+		message
+	}))];
+	for (const { field } of split.when.timeTerms) if (!timeTypes.has(timeField(model, field)?.type ?? "")) problems.push({
+		field: "when",
+		message: `${field} is not a timestamp or date field of ${spec.resource}`
+	});
+	const parsed = parseFilter(spec.when);
+	if (usesSearch(parsed.ast)) problems.push({
+		field: "when",
+		message: "cannot use search() or similar()"
+	});
+	const checked = parsed.ast && checkFilter(model, parsed.ast);
+	if (checked && !checked.ok) problems.push(...checked.errors.map((error) => ({
+		field: "when",
+		message: error.message
+	})));
+	return problems;
+};
+//#endregion
+export { readyProblems };

package/dist/workflows/ready/ready-start.js

@@ -0,0 +1,104 @@
+import { HttpProblem } from "../../problem.js";
+import { assistantRecords } from "../../assistant/records.js";
+import { saverSession } from "../plugin-records.js";
+import { startWorkflow } from "../start-workflow.js";
+import { triggerFailed, triggerRecovered } from "../triggers/trigger-row.js";
+import { encodeKey } from "@protobase/schema/internal";
+import { checkFilter, evaluateFilter, parseFilter } from "@protobase/schema";
+import { sql } from "kysely";
+import { createHash } from "node:crypto";
+import { StepError } from "@protobase/workflows";
+//#region src/workflows/ready/ready-start.ts
+/** The most characters of a run's key; a longer ready key is kept as its SHA-256. */
+const keyLength = 200;
+/**
+* The resource, the record key and the values of the `key` fields: the key a record starts one run under, so a trigger
+* moved to another resource starts its records afresh.
+*/
+const readyKey = (resource, model, record, keyFields = []) => {
+	const key = `record:${JSON.stringify(resource)}:${encodeKey(model.primaryKey.map((name) => record[name]))}${keyFields.map((name) => `:${JSON.stringify(record[name] ?? null)}`).join("")}`;
+	return key.length <= keyLength ? key : `record:sha256:${createHash("sha256").update(key).digest("hex")}`;
+};
+const holds = (model, when, record) => {
+	if (when === void 0) return true;
+	const parsed = parseFilter(when);
+	const checked = parsed.ast && checkFilter(model, parsed.ast);
+	if (!checked) return true;
+	if (!checked.ok) return false;
+	return Boolean(evaluateFilter(checked.filter, record));
+};
+/**
+* Why a trigger may not go on reading as its saver: they hold no role any more or are gone, or the API refuses them
+* (401, 403); `undefined` for any other error, such as a busy database, which the job retries.
+*/
+const refusal = (error) => {
+	if (error instanceof StepError) return error.reason;
+	if (error instanceof HttpProblem && (error.status === 401 || error.status === 403)) return `${error.status} ${error.title}`;
+};
+/** The work's value, or the refusal that stopped it; any other error is thrown on. */
+const orRefusal = (work) => work.then((value) => ({ value }), (error) => {
+	const reason = refusal(error);
+	if (reason === void 0) throw error;
+	return { refused: reason };
+});
+/** What a ready trigger works on: its declaration, resource, and the records API as the user who saved its version. */
+const readyContext = async ({ deps, roles, declared }, trigger) => {
+	const spec = declared(trigger.type)?.ready(trigger.input);
+	const model = spec && deps().registry.find(spec.resource)?.model;
+	if (!spec || !model) return;
+	const session = await saverSession(roles, trigger.saved_by, trigger.tenant_id ?? void 0);
+	return {
+		spec,
+		model,
+		records: assistantRecords(deps(), session)
+	};
+};
+/**
+* Starts a run of the record if it is ready now: one read of it through the API as the user who saved the enabled
+* version, so their access rules, tenant scope and field access decide what the run sees, `when` evaluated on what they
+* read, then one keyed insert, so a record starts once per ready key. A record that is gone, or that they may not read,
+* starts nothing; a refused saver, or a key field they cannot read, marks the trigger failing, and a failing trigger
+* that reads a record is active again. Answers whether this check brought the trigger back, so its records are passed
+* over again for what it missed.
+*/
+const startIfReady = async (input, db, trigger, key) => {
+	const failed = (message) => triggerFailed(db, input.schema, trigger, "refused", message).then(() => false);
+	const found = await orRefusal(readyContext(input, trigger));
+	if ("refused" in found) return failed(found.refused);
+	const context = found.value;
+	if (!context) return false;
+	const { spec, model, records } = context;
+	const keyValues = model.primaryKey.map((name) => key[name]);
+	const got = await orRefusal(records.get(spec.resource, keyValues.length === 1 ? keyValues[0] : keyValues).catch((error) => {
+		if (error instanceof HttpProblem && error.status === 404) return;
+		throw error;
+	}));
+	if ("refused" in got) return failed(got.refused);
+	const read = got.value;
+	if (!read) return false;
+	const { etag: _, permissions: __, ...record } = read.record;
+	const hidden = (spec.key ?? []).find((name) => !(name in record));
+	if (hidden) return failed(`the key field ${hidden} is not readable by the user who saved the workflow`);
+	const recovered = trigger.status === "failing" && await triggerRecovered(db, input.schema, trigger);
+	if (!holds(model, spec.when, record)) return recovered;
+	await db.transaction().execute(async (trx) => {
+		const { rows } = await sql`select enabled_version from ${sql.id(input.schema, "workflows")} where id = ${trigger.workflow_id} for share`.execute(trx);
+		if (rows[0]?.enabled_version !== trigger.version) return;
+		await startWorkflow(trx, {
+			workflow: trigger.workflow_id,
+			version: trigger.version,
+			input: {
+				resource: spec.resource,
+				key: encodeKey(model.primaryKey.map((name) => record[name])),
+				record
+			},
+			...trigger.tenant_id !== null && { tenant: trigger.tenant_id },
+			startedBy: `trigger:${trigger.id}`,
+			key: readyKey(spec.resource, model, record, spec.key),
+			schema: input.schema
+		});
+	});
+	return recovered;
+};
+//#endregion
+export { orRefusal, readyContext, readyKey, refusal, startIfReady };

package/dist/workflows/ready/ready-when.js

@@ -0,0 +1,101 @@
+import { parseFilter, printFilter } from "@protobase/schema";
+//#region src/workflows/ready/ready-when.ts
+const unitMs = {
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5,
+	w: 6048e5
+};
+/** The longest wait a time term may say, 100 years, so a ready time stays a date JavaScript can hold. */
+const maxAfterMs = 31536e8;
+const usesNow = (node) => {
+	if (typeof node !== "object" || node === null) return false;
+	if (node.kind === "now") return true;
+	return Object.values(node).some(usesNow);
+};
+const timeTerm = (term) => {
+	if (term.kind !== "compare" || term.op !== "<=" && term.op !== "<" || term.value.kind !== "now" || term.field.path.length !== 1) return;
+	const offset = term.value.offset;
+	if (offset && offset.sign !== "-") return;
+	const afterMs = (offset ? offset.duration.amount * unitMs[offset.duration.unit] : 0) + (term.op === "<" ? 1 : 0);
+	return {
+		field: term.field.path[0],
+		afterMs
+	};
+};
+/**
+* Splits a ready trigger's `when`: `now()` may stand only in top-level AND terms of the form `<timestamp field> <=
+* now() - <duration>` (or `<`), which say when a record becomes ready, so the start waits until then and nothing sweeps.
+* Any other use of `now()` is refused, naming the term.
+*/
+const readyWhen = (when) => {
+	if (when === void 0) return {
+		ok: true,
+		when: {
+			filter: void 0,
+			timeTerms: []
+		}
+	};
+	const parsed = parseFilter(when);
+	if (!parsed.ok) return {
+		ok: false,
+		problems: parsed.errors.map((error) => error.message)
+	};
+	if (!parsed.ast) return {
+		ok: true,
+		when: {
+			filter: void 0,
+			timeTerms: []
+		}
+	};
+	const terms = parsed.ast.kind === "and" ? parsed.ast.args : [parsed.ast];
+	const timeTerms = [];
+	const rest = [];
+	const problems = [];
+	for (const term of terms) {
+		const time = timeTerm(term);
+		if (time && time.afterMs > 31536e8) problems.push(`"${printFilter(term)}" waits longer than 100 years`);
+		else if (time) timeTerms.push(time);
+		else if (usesNow(term)) problems.push(`"${printFilter(term)}" uses now() other than as <timestamp field> <= now() - <duration> joined by AND`);
+		else rest.push(term);
+	}
+	if (problems.length > 0) return {
+		ok: false,
+		problems
+	};
+	return {
+		ok: true,
+		when: {
+			filter: rest.length === 0 ? void 0 : rest.length === 1 ? rest[0] : {
+				kind: "and",
+				args: rest,
+				span: parsed.ast.span
+			},
+			timeTerms
+		}
+	};
+};
+/** When a record becomes ready by its time terms: the latest of them, now when it has none, undefined when a time is unset. */
+const readyAt = (timeTerms, record, now) => {
+	let at = now.getTime();
+	for (const { field, afterMs } of timeTerms) {
+		const value = record[field];
+		if (value === null || value === void 0) return;
+		const time = new Date(value).getTime();
+		if (Number.isNaN(time)) return;
+		at = Math.max(at, time + afterMs);
+	}
+	const ready = new Date(at);
+	if (Number.isNaN(ready.getTime())) return;
+	return ready;
+};
+/** The field a time term names, by its name or one of its aliases, as the record read carries it. */
+const timeField = (model, name) => Object.values(model.fields).find((field) => field.name === name || field.aliases.includes(name));
+/** The time terms with each field named as the record carries it; a term on no field of the model keeps its name. */
+const resolveTimeTerms = (model, terms) => terms.map((term) => ({
+	...term,
+	field: timeField(model, term.field)?.name ?? term.field
+}));
+//#endregion
+export { maxAfterMs, readyAt, readyWhen, resolveTimeTerms, timeField };

package/dist/workflows/run-files.js

@@ -1,6 +1,7 @@
 import { cleanName, formatUri, parseUri } from "../files/uri.js";
 import { readLimited } from "../webhooks/table/read-limited.js";
 import { StepError } from "@protobase/workflows";
+import { isFileValue } from "@protobase/workflows/plugin";
 //#region src/workflows/run-files.ts
 /** The most bytes of one file a workflow stores or reads, as the `http` step reads at most. */
 const runFileLimit = 10485760;
@@ -15,10 +16,11 @@ const runStore = (files) => {
 };
 /**
 * Stores bytes a step of the run got, such as an answer's body, as a file of the run's own, under a name of the
-* runner's choosing: no part of its path comes from the workflow or the answer.
+* runner's choosing: no part of its path comes from the workflow or the answer. At most `runFileLimit` bytes.
 */
 const storeRunFile = async (files, runId, bytes, name, type) => {
 	const store = runStore(files);
+	if (bytes.length > 10485760) throw new StepError("States.TaskFailed", `${cleanName(name)} is larger than ${runFileLimit / 1024 / 1024} MiB, the most a run keeps of one file`);
 	const path = `${prefix(runId)}${crypto.randomUUID()}`;
 	await store.put(path, new Blob([bytes]).stream());
 	const clean = cleanName(name);
@@ -34,12 +36,6 @@ const storeRunFile = async (files, runId, bytes, name, type) => {
 		size: bytes.length
 	};
 };
-/** Whether a value has a file value's shape, all four fields; an object with only a `uri` is other data. */
-const isFileValue = (value) => {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const { uri, name, type, size } = value;
-	return typeof uri === "string" && typeof name === "string" && typeof type === "string" && typeof size === "number";
-};
 /**
 * The file a file value names, when it is one the run stored itself; a step fails on any other, so a workflow cannot
 * mail, send or attach a file of the app's by naming its URI.

package/dist/workflows/save-hook.js

@@ -1,22 +1,23 @@
 import { badRequest } from "../problem.js";
-import { requiredStepInputs } from "@protobase/schema/internal";
+import { syncTrigger } from "./triggers/trigger-sync.js";
 import { sql } from "kysely";
 import { checkDefinition, problemText } from "@protobase/workflows";
 //#region src/workflows/save-hook.ts
 /**
-* Checks a workflow's definition on every save that changes it, against the language's schema and the named-reads
-* profile, with the step types the app has, and keeps it as the version the table's trigger numbered, saved by the
-* caller. A refusal is a 400 problem naming each state and field, also listed as `problems`, and as the `definition`
-* field's `errors` with the state and field in their `params`, for a form to show each on its step; the write rolls back.
+* Checks a workflow's definition on every save that changes it, and as it is turned on (not off), against the language's schema
+* and the named-reads profile, with the trigger and step types the app has, and keeps a changed definition as the
+* version the table's trigger numbered, saved by the caller. Then it keeps the workflow's trigger in step with its
+* enabled version. A refusal is a 400 problem naming each state and field, also listed as `problems`, and as the
+* `definition` field's `errors` with the state and field in their `params`, for a form to show each on its step; the
+* write rolls back.
 */
-const workflowSaveHook = (schema, stepTypes) => async (event, trx) => {
+const workflowSaveHook = (schema, types, jobs) => async (event, trx) => {
 	if (event.resource.name !== "workflows" || !event.after) return;
 	if (event.operation !== "create" && event.operation !== "update") return;
-	if (event.operation === "update" && event.after.version === event.before?.version) return;
-	const problems = checkDefinition(event.after.definition, {
-		resources: stepTypes,
-		required: requiredStepInputs
-	});
+	const changed = event.operation === "create" || event.after.version !== event.before?.version;
+	const enabling = event.after.enabled_version !== (event.before?.enabled_version ?? null);
+	if (!changed && !enabling) return;
+	const problems = changed || event.after.enabled_version !== null ? checkDefinition(event.after.definition, types) : [];
 	if (problems.length > 0) {
 		const errors = problems.map((problem) => ({
 			code: "invalid-workflow",
@@ -32,8 +33,9 @@ const workflowSaveHook = (schema, stepTypes) => async (event, trx) => {
 			errors
 		});
 	}
-	await sql`insert into ${sql.id(schema, "versions")} (workflow_id, version, definition, saved_by, tenant_id)
-    select w.id, w.version, w.definition, ${String(event.user.id)}, w.tenant_id from ${sql.id(schema, "workflows")} w where w.id = ${String(event.after.id)}`.execute(trx);
+	if (changed) await sql`insert into ${sql.id(schema, "versions")} (workflow_id, version, definition, saved_by, tenant_id)
+      select w.id, w.version, w.definition, ${String(event.user.id)}, w.tenant_id from ${sql.id(schema, "workflows")} w where w.id = ${String(event.after.id)}`.execute(trx);
+	await syncTrigger(trx, schema, jobs, event.after);
 };
 //#endregion
 export { workflowSaveHook };

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 4`;
+const workflowsComment = `Protobase workflows 6`;
 const commentVersion = (comment) => {
 	const match = comment?.match(/^Protobase workflows (\d+)$/);
 	return match ? Number(match[1]) : void 0;
@@ -78,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);
@@ -118,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
@@ -138,7 +197,10 @@ 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;
@@ -150,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) === 4 && 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")};`;