@protobase/cli 0.67.7 → 0.67.9

package/dist/cli/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.67.7";
+var version = "0.67.9";
 //#endregion
 export { version };

package/dist/config/build-project.js

@@ -1,4 +1,4 @@
-import { projectFiles, projectFunctions, projectJobs, projectNotifications, projectOptions, projectResources, projectWebhooks } from "./project-parts.js";
+import { projectFiles, projectFunctions, projectJobs, projectNotifications, projectOptions, projectResources, projectWebhooks, projectWorkflows } from "./project-parts.js";
 import { userTablesOn } from "./user-tables-config.js";
 import { buildAppAuth, buildAuthenticator, checkCallsOptions, checkStatusOptions } from "@protobase/server/internal";
 //#region src/config/build-project.ts
@@ -44,13 +44,14 @@ const projectAuthenticate = async (config, auth) => {
 };
 /** The app, built from its merged config over its database: every reference loaded, auth and the authenticator made. */
 const buildProject = async (config, database) => {
-	const [resources, functions, files, options, auth, webhooks, notifications, mailer] = await Promise.all([
+	const [resources, functions, files, options, auth, webhooks, workflows, notifications, mailer] = await Promise.all([
 		projectResources(config),
 		projectFunctions(config),
 		projectFiles(config),
 		projectOptions(config),
 		projectAuth(config, database),
 		projectWebhooks(config),
+		projectWorkflows(config),
 		projectNotifications(config),
 		projectMailer(config)
 	]);
@@ -69,6 +70,7 @@ const buildProject = async (config, database) => {
 		...config.events && { events: config.events },
 		...config.history && { history: config.history },
 		...webhooks && { webhooks },
+		...workflows && { workflows },
 		...config.realtime && { realtime: config.realtime },
 		...notifications && { notifications },
 		...config.status && { status: checkStatusOptions(config.status) },

package/dist/config/project-parts.js

@@ -1,5 +1,5 @@
 import { checkUnique } from "./merge-config.js";
-import { checkNotificationsOptions, declaredJob, fileProviderOf, isSubscription, webhooksModule } from "@protobase/server/internal";
+import { checkNotificationsOptions, declaredJob, fileProviderOf, isSubscription, webhooksModule, workflowsModule } from "@protobase/server/internal";
 import { isPageDefinition } from "@protobase/layout";
 //#region src/config/project-parts.ts
 /** The config modules' exports as one module: every value once, under a key no other config uses. */
@@ -38,7 +38,7 @@ const mergedModule = (modules) => {
 	}
 	return merged;
 };
-/** The resources, views, pages and subscriptions of every config's config/ folder, after the webhook pages of `webhooks`. */
+/** The resources, views, pages and subscriptions of every config's config/ folder, after the pages of `webhooks` and `workflows`. */
 const projectResources = async (config) => {
 	const modules = await Promise.all(config.sources.flatMap(({ files, label }) => files.resources ? [files.resources().then((module) => ({
 		module,
@@ -48,7 +48,15 @@ const projectResources = async (config) => {
 		module: webhooksModule(config.webhooks),
 		label: "protobase-webhooks"
 	}] : [];
-	return mergedModule([...webhooks, ...modules]);
+	const workflows = config.workflows ? [{
+		module: workflowsModule(config.workflows),
+		label: "protobase-workflows"
+	}] : [];
+	return mergedModule([
+		...webhooks,
+		...workflows,
+		...modules
+	]);
 };
 /** The declared jobs, each run by the default export of its jobs/<name>.ts, loaded on its first run; schedules in the app's `timezone` unless a job names its own. */
 const projectJobs = (config) => Object.entries(config.jobs).map(([name, { declaration, files, label }]) => {
@@ -184,6 +192,15 @@ const projectWebhooks = async (config) => {
 		...ownerRoles && { ownerRoles }
 	};
 };
+/** The workflows options, with the roles of workflows/saved-by-roles.ts when a config's folder has it. */
+const projectWorkflows = async (config) => {
+	if (!config.workflows) return void 0;
+	const savedByRoles = await lastDefault(config, "workflows/saved-by-roles.ts");
+	return {
+		...config.workflows,
+		...savedByRoles && { savedByRoles }
+	};
+};
 /**
 * The notifications options, checked, with what the conventions find in notifications/: the device store of store.ts,
 * the history store of history-store.ts and the push senders of senders.ts, each its default export.
@@ -203,4 +220,4 @@ const projectNotifications = async (config) => {
 	});
 };
 //#endregion
-export { lastModule, mergedModule, projectAssistantTools, projectFiles, projectFunctions, projectJobs, projectMcpTools, projectNotifications, projectOptions, projectResources, projectRoles, projectWebhooks, projectWriteHooks };
+export { lastModule, mergedModule, projectAssistantTools, projectFiles, projectFunctions, projectJobs, projectMcpTools, projectNotifications, projectOptions, projectResources, projectRoles, projectWebhooks, projectWorkflows, projectWriteHooks };

package/dist/dev/entry.js

@@ -7,7 +7,7 @@ import { devRealtimePrune } from "./dev-prune.js";
 import { devDatabase, loadDevConfig } from "./project.js";
 import { withDevServiceWorker } from "./service-worker-route.js";
 import { setMissing, supabaseEnv } from "./supabase-env.js";
-import { apiKeySettings, assistantSettings, authSchemaDrift, authStoreTables, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, configExports, hasUsers, relayed, sqlSends } from "@protobase/server";
+import { apiKeySettings, assistantSettings, authSchemaDrift, authStoreTables, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, checkWorkflowsSchema, configExports, hasUsers, relayed, sqlSends } from "@protobase/server";
 import { upgradeWebSocket } from "@hono/node-server";
 import { Hono } from "hono";
 //#region src/dev/entry.ts
@@ -38,6 +38,7 @@ checkAi({
 	env: process.env
 });
 if (project.webhooks) await checkWebhooksSchema(db, project.webhooks);
+if (project.workflows) await checkWorkflowsSchema(db, project.workflows);
 if (relayed(project.realtime)) await checkRealtimeRelay(db);
 if (sqlSends(project.realtime)) await checkChannelSends(db);
 if (project.notifications) await checkNotificationsSchema(db, project.notifications, project.auth);

package/dist/doctor/built-in-models.js

@@ -1,25 +1,31 @@
-import { builtInResources, configExports, webhooksModule } from "@protobase/server/config-exports";
+import { builtInResources, configExports, webhooksModule, workflowsModule } from "@protobase/server/config-exports";
 //#region src/doctor/built-in-models.ts
 /**
 * The resources and views Protobase adds to an app by what its config enables, as the API serves them: the webhook ones
-* of `webhooks`, then Failed jobs, Activity and Comments by what the app's resources use. Doctor checks them as it checks
+* of `webhooks` and the workflow ones of `workflows`, then Failed jobs, Activity and Comments by what the app's resources use. Doctor checks them as it checks
 * the app's own.
 */
 const builtInModels = (config, models) => {
-	const webhooks = config.webhooks ? configExports(webhooksModule(config.webhooks)) : {
+	const none = {
 		resources: [],
 		views: []
 	};
-	const webhookModels = webhooks.resources.map((resource) => resource.toModel());
+	const webhooks = config.webhooks ? configExports(webhooksModule(config.webhooks)) : none;
+	const workflows = config.workflows ? configExports(workflowsModule(config.workflows)) : none;
+	const moduleModels = [...webhooks.resources, ...workflows.resources].map((resource) => resource.toModel());
 	const added = builtInResources({
-		models: [...webhookModels, ...models],
+		models: [...moduleModels, ...models],
 		jobs: Object.keys(config.jobs).length > 0,
 		notifications: config.notifications !== void 0,
 		...config.events && { events: config.events }
 	});
 	return {
-		models: [...webhookModels, ...added.resources.map((resource) => resource.toModel())],
-		views: [...webhooks.views, ...added.views].map((view) => view.toModel())
+		models: [...moduleModels, ...added.resources.map((resource) => resource.toModel())],
+		views: [
+			...webhooks.views,
+			...workflows.views,
+			...added.views
+		].map((view) => view.toModel())
 	};
 };
 /**

package/dist/migration/load-project.js

@@ -40,6 +40,7 @@ const migrationProject = async (config, url) => {
 		...auth && { auth },
 		...config.events && { events: config.events },
 		...webhooks && { webhooks },
+		...config.workflows && { workflows: config.workflows },
 		...config.realtime && { realtime: config.realtime },
 		...config.calls && { calls: config.calls },
 		...notifications && { notifications },

package/dist/migration/parts.js

@@ -1,5 +1,5 @@
 import { authMigrationTitle } from "../auth/migration-file.js";
-import { authSchemaMigration, callsMigration, changesMigration, channelSendsMigration, commentsMigration, computedMigration, isCaptured, jobsSchemaMigration, notificationsMigration, ownedDefinitionsMigration, queryRunnerMigration, realtimeRelayMigration, relayed, sqlSends, statusMigration, userTablesMigration, webhooksMigration } from "@protobase/server";
+import { authSchemaMigration, callsMigration, changesMigration, channelSendsMigration, commentsMigration, computedMigration, isCaptured, jobsSchemaMigration, notificationsMigration, ownedDefinitionsMigration, queryRunnerMigration, realtimeRelayMigration, relayed, sqlSends, statusMigration, userTablesMigration, webhooksMigration, workflowsMigration } from "@protobase/server";
 //#region src/migration/parts.ts
 /** Every feature the project's config enables, in the order their files are written. */
 const migrationParts = (project) => {
@@ -11,7 +11,7 @@ const migrationParts = (project) => {
 			title: authMigrationTitle,
 			sql: () => authSchemaMigration(project.auth)
 		}] : [],
-		...project.jobs.length > 0 || project.models.some(isCaptured) || comments || aiFields || project.webhooks || project.notifications ? [{
+		...project.jobs.length > 0 || project.models.some(isCaptured) || comments || aiFields || project.webhooks || project.workflows || project.notifications ? [{
 			name: "jobs",
 			title: "The jobs schema this version of Protobase needs",
 			sql: () => jobsSchemaMigration(project.db)
@@ -41,6 +41,11 @@ const migrationParts = (project) => {
 			title: "The webhook subscriptions of webhooks",
 			sql: () => webhooksMigration(project.db, project.webhooks, project.events)
 		}] : [],
+		...project.workflows ? [{
+			name: "workflows",
+			title: "The workflows, their versions, runs and steps",
+			sql: () => workflowsMigration(project.db, project.workflows)
+		}] : [],
 		...project.notifications && !(project.notifications.store && project.notifications.historyStore) ? [{
 			name: "notifications",
 			title: "The tables of notifications",

package/dist/project/project-admin.js

@@ -32,6 +32,7 @@ const projectAdmin = (project, db, ui, reporter, upgradeWebSocket, userTables) =
 		...project.events && { events: project.events },
 		...project.history && { history: project.history },
 		...project.webhooks && { webhooks: project.webhooks },
+		...project.workflows && { workflows: project.workflows },
 		...project.realtime && { realtime: project.realtime },
 		...project.notifications && { notifications: project.notifications },
 		...project.status && { status: project.status },

package/dist/serve/lifecycle.js

@@ -9,7 +9,7 @@ import { startCleanupTimer } from "./cleanup-timer.js";
 import { closeSockets } from "./close-sockets.js";
 import { servedRelease } from "./mobile-release.js";
 import pg from "pg";
-import { assistantSettings, authStoreTables, backgroundSettled, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, configExports, createFileCleanup, relayed, sqlSends, startJobs } from "@protobase/server";
+import { assistantSettings, authStoreTables, backgroundSettled, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, checkWorkflowsSchema, configExports, createFileCleanup, relayed, sqlSends, startJobs } from "@protobase/server";
 import { createAdaptorServer, upgradeWebSocket } from "@hono/node-server";
 //#region src/serve/lifecycle.ts
 const listen = (server, port) => new Promise((resolve, reject) => {
@@ -44,6 +44,7 @@ const startServe = async ({ config, env, openDb = (url) => openAppDatabase(pg, u
 			env: process.env
 		});
 		if (env.startupChecks && project.webhooks) await checkWebhooksSchema(db, project.webhooks);
+		if (env.startupChecks && project.workflows) await checkWorkflowsSchema(db, project.workflows);
 		if (env.startupChecks && relayed(project.realtime)) await checkRealtimeRelay(db);
 		if (env.startupChecks && sqlSends(project.realtime)) await checkChannelSends(db);
 		if (env.startupChecks && project.notifications) await checkNotificationsSchema(db, project.notifications, project.auth);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.67.7",
+  "version": "0.67.9",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,12 +43,12 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.67.7",
-    "@protobase/layout": "0.67.7",
-    "@protobase/query": "0.67.7",
-    "@protobase/schema": "0.67.7",
-    "@protobase/server": "0.67.7",
-    "@protobase/ui": "0.67.7",
+    "@protobase/config": "0.67.9",
+    "@protobase/layout": "0.67.9",
+    "@protobase/query": "0.67.9",
+    "@protobase/schema": "0.67.9",
+    "@protobase/server": "0.67.9",
+    "@protobase/ui": "0.67.9",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/SKILL.md

@@ -88,6 +88,7 @@ Reference:
 - When filling fields with a model → read [AI fields and actions](references/reference/ai.md)
 - When letting people without an account create records → read [Public forms](references/reference/forms.md)
 - When running background jobs → read [Jobs](references/reference/jobs.md)
+- When writing or running workflows, their steps and their runs → read [Workflows](references/reference/workflows.md)
 - When sending email → read [Email](references/reference/email.md)
 - When making a PDF file, such as an invoice, a quote or a report → read [PDF documents](references/reference/pdf.md)
 - When registering users' devices for push notifications → read [Notifications](references/reference/notifications.md)

package/skills/protobase/references/features/workflows.md

@@ -0,0 +1,16 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/features/workflows.md: run `bun run docs:skill`, do not edit. -->
+
+# Workflows
+
+Graphs of steps the server runs along their edges, written in a language a model writes well, with every step recorded.
+
+- [Workflows](../reference/workflows.md#turning-them-on) (beta): Workflows kept in the app's database, each changed definition checked and kept as a version, run on the app's own jobs.
+- [Workflow language](../reference/workflows.md#the-document) (beta): The States Language with JSONata expressions, every value read by name, so a model writes and edits it as a small, local change.
+- [Checked on save](../reference/workflows.md#reading-values-by-name) (beta): A definition that does not fit the language, has an edge to no step or reads a value nothing gives is refused, naming the step and the field.
+- [Branches, steps per item and retries](../reference/workflows.md#states) (beta): Choices, a step per item with their results merged, waits, and per-step retries, timeouts and error paths.
+- [HTTP request step](../reference/workflows.md#apphttp) (beta): Calls a URL built at run time through the outgoing-address guard, only at public addresses unless the config allows private ones, reading at most 10 MiB of the answer as JSON, text or a file.
+- [Records steps](../reference/workflows.md#apprecords) (beta): Create, update, get and list records as the workflow's last editor, with the roles they hold now.
+- [Mail step](../reference/workflows.md#appmailsend) (beta): Sends mail, with files the run downloaded attached, from the app's own sender.
+- [Runs and step records](../reference/workflows.md#runs-and-their-steps) (beta): Each run started by hand through the API or from the app's code, with every step's input, output, logs, timing, tries and error recorded, secrets blanked out.
+- [Runs that survive restarts](../reference/workflows.md#how-a-run-is-run) (beta): A run takes up where it stood after a restart or a crashed worker, never running a saved step again, and every limit fails closed.
+- [Who may run workflows](../reference/workflows.md#who-may-do-what) (beta): Making, changing and running workflows and reading their runs are each granted by name, within the tenant.

package/skills/protobase/references/features.md

@@ -32,6 +32,7 @@ A feature without a mark is stable. The others say so after their name:
 - [Files and images](features/files-and-images.md): Uploaded files and images, where they are kept and how they are served.
 - [History, comments and live updates](features/history-comments-and-live-updates.md): The changes of each record, comments on it, and pages that refresh as records change.
 - [Events, webhooks and jobs](features/events-webhooks-and-jobs.md): React to changes, deliver them to other systems, and run work in the background.
+- [Workflows](features/workflows.md): Graphs of steps the server runs along their edges, written in a language a model writes well, with every step recorded.
 - [Notifications](features/notifications.md): A bell in the top bar and push to browsers and phones, for what your app tells its users.
 - [Calls](features/calls.md): Audio and video calls between an app's users, with Protobase deciding who is in a call and who hears whom.
 - [Email and public forms](features/email-and-public-forms.md): Mail the app sends, the PDF documents it makes, and forms for people without an account.

package/skills/protobase/references/reference/cli.md

@@ -595,7 +595,7 @@ Applies the project's `db/migrations/*.sql` that the database has not applied ye
 protobase migration [--dir db/migrations] [--extend <dir>]
 ```
 
-Writes what the database still needs for every feature the config enables, as the project's next migrations in `--dir`, one file per feature: the auth schema when sign-in is on (`NNN_auth.sql`, as [`auth migration`](#auth-migration) writes it), the [jobs schema](jobs.md#the-jobs-schema) when the config has jobs, `webhooks` or `notifications`, or a resource has events, history, comments or an [AI field](ai.md) (`NNN_jobs.sql`), the [capture of events](events.md#migrations-and-startup) and the [history table](history.md#the-table) (`NNN_changes.sql`), the columns of [rollup and formula fields](data-config.md#rollups-and-formulas) and the triggers that keep the rollups (`NNN_computed.sql`), the role the [assistant's read-only queries](assistant.md#the-built-in-backend) run as, when it finds the built-in assistant's key (`NNN_query.sql`), the [comments table](comments.md#the-table) (`NNN_comments.sql`), the [webhook subscriptions](webhooks.md#subscriptions-in-the-admin-app) of `webhooks` (`NNN_webhooks.sql`), the [devices and history tables](notifications.md#table-names) of `notifications` (`NNN_notifications.sql`), the `realtime_relay` schema of [`realtime: { processes: 'many' }`](supabase-realtime.md#several-processes) (`NNN_realtime_relay.sql`), the `channels` schema of [`realtime: { sqlSends: true }`](channels.md#from-sql) (`NNN_channel_sends.sql`), and, with [`userTables`](user-tables.md#the-switch), the schemas of user tables (`NNN_user_tables.sql`) and the delete of the definitions of tables that resources in code [own now](user-tables.md#taking-a-table-over-as-code) (`NNN_owned_definitions.sql`). It compares the database, with the project's migrations applied, with the config (for the auth schema, it reads the store's record of the migrations it applied), merged with those of `--extend` as `dev` merges them, and writes nothing when the database is current. Apply the files with the project's other migrations. It reads the `.env` nearest the current directory and needs `DATABASE_URL`.
+Writes what the database still needs for every feature the config enables, as the project's next migrations in `--dir`, one file per feature: the auth schema when sign-in is on (`NNN_auth.sql`, as [`auth migration`](#auth-migration) writes it), the [jobs schema](jobs.md#the-jobs-schema) when the config has jobs, `webhooks`, `workflows` or `notifications`, or a resource has events, history, comments or an [AI field](ai.md) (`NNN_jobs.sql`), the [capture of events](events.md#migrations-and-startup) and the [history table](history.md#the-table) (`NNN_changes.sql`), the columns of [rollup and formula fields](data-config.md#rollups-and-formulas) and the triggers that keep the rollups (`NNN_computed.sql`), the role the [assistant's read-only queries](assistant.md#the-built-in-backend) run as, when it finds the built-in assistant's key (`NNN_query.sql`), the [comments table](comments.md#the-table) (`NNN_comments.sql`), the [webhook subscriptions](webhooks.md#subscriptions-in-the-admin-app) of `webhooks` (`NNN_webhooks.sql`), the [workflows, versions, runs and steps](workflows.md#turning-them-on) of `workflows` (`NNN_workflows.sql`), the [devices and history tables](notifications.md#table-names) of `notifications` (`NNN_notifications.sql`), the `realtime_relay` schema of [`realtime: { processes: 'many' }`](supabase-realtime.md#several-processes) (`NNN_realtime_relay.sql`), the `channels` schema of [`realtime: { sqlSends: true }`](channels.md#from-sql) (`NNN_channel_sends.sql`), and, with [`userTables`](user-tables.md#the-switch), the schemas of user tables (`NNN_user_tables.sql`) and the delete of the definitions of tables that resources in code [own now](user-tables.md#taking-a-table-over-as-code) (`NNN_owned_definitions.sql`). It compares the database, with the project's migrations applied, with the config (for the auth schema, it reads the store's record of the migrations it applied), merged with those of `--extend` as `dev` merges them, and writes nothing when the database is current. Apply the files with the project's other migrations. It reads the `.env` nearest the current directory and needs `DATABASE_URL`.
 
 ```sh
 bun run db:migrate                # the database at the project's current schema

package/skills/protobase/references/reference/config/jobs-and-events.md

@@ -2,7 +2,7 @@
 
 # Jobs and events options
 
-The config keys of what the app does in the background and records as it changes, jobs, events, history, webhooks, notifications and status, with their types and defaults, and the files where a job's run and the stores of its own go.
+The config keys of what the app does in the background and records as it changes, jobs, events, history, webhooks, workflows, notifications and status, with their types and defaults, and the files where a job's run and the stores of its own go.
 
 The keys of the app's background work and of what it keeps as records change, at the top level of [`protobase.config.ts`](../config.md).
 
@@ -209,6 +209,50 @@ Lets subscriptions send to private, loopback and link-local addresses, for devel
 export default defineConfig(({ command }) => ({ webhooks: { allowPrivateAddresses: command === 'dev' } }))
 ```
 
+## workflows
+
+- **Type:** `{ schema?: string; secrets?: string[]; allowPrivateAddresses?: boolean }`
+- **Default:** off; `{}` turns them on
+
+Workflows that people and models make in the app, kept with their versions, runs and steps in a schema of the app's database that `protobase migration` writes, and run by the `workflows.segment` job. Records steps act as each workflow's last editor, with the roles they hold now, read from the app's sign-in; a project that signs people in otherwise exports its own, `async ({ id, tenant }) => [...]`, as the default of `workflows/saved-by-roles.ts`. See [Workflows](../workflows.md).
+
+```ts
+export default defineConfig({ workflows: {} })
+```
+
+## workflows.schema
+
+- **Type:** `string`
+- **Default:** `workflows`
+
+The schema of the workflows, their versions, runs and steps.
+
+```ts
+export default defineConfig({ workflows: { schema: 'flows' } })
+```
+
+## workflows.secrets
+
+- **Type:** `string[]`
+- **Default:** none
+
+The environment variables workflows may read, each as `$states.context.Secrets.<NAME>`; no other variable is reachable from a workflow. Their values are blanked out of everything a run records but its input, which is kept as its caller gave it. Startup stops when one is unset or shorter than 8 characters.
+
+```ts
+export default defineConfig({ workflows: { secrets: ['TICKETS_TOKEN'] } })
+```
+
+## workflows.allowPrivateAddresses
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Lets the `app:http` step reach private, loopback and link-local addresses, for development and tests. Off, a URL whose host resolves to one fails the step, which connects only to the address it checked, so a workflow cannot reach the app's own network.
+
+```ts
+export default defineConfig(({ command }) => ({ workflows: { allowPrivateAddresses: command === 'dev' } }))
+```
+
 ## notifications
 
 - **Type:** `{ ui?: boolean; schema?: string; devices?: { table?: string; columns?: Record<string, string> }; history?: { table?: string; columns?: Record<string, string> } }`

package/skills/protobase/references/reference/config.md

@@ -30,7 +30,7 @@ Each key is described with its type and default in the option pages:
 | [Sign-in options](config/sign-in.md) | `auth`, `authenticate`, `signingKeyDays`, `signingKeyGraceDays` |
 | [API options](config/api.md) | `apiPath`, `apiKeys`, `cors`, `defaultAccess`, `rowPermissions`, `statementTimeoutMs`, `scanGuard`, `errorReporting`, `writeHooks`, `mcpEndpoint`, `remoteResources`, `runtimeUpdates`, `realtime`, `calls`, `userTables` |
 | [Admin app options](config/admin-app.md) | `assistant`, `maps`, `plugins` |
-| [Jobs and events options](config/jobs-and-events.md) | `jobs`, `events`, `history`, `webhooks`, `notifications`, `status` |
+| [Jobs and events options](config/jobs-and-events.md) | `jobs`, `events`, `history`, `webhooks`, `workflows`, `notifications`, `status` |
 | [Files options](config/files.md) | `files` |
 
 ## Config types
@@ -140,6 +140,7 @@ The other files belong to an option, and are described with it:
 | `mcp/tools.ts` | [`mcpEndpoint`](config/api.md#mcpendpoint) |
 | `jobs/<name>.ts` | [`jobs`](config/jobs-and-events.md#jobs) |
 | `webhooks/owner-roles.ts` | [`webhooks`](config/jobs-and-events.md#webhooks) |
+| `workflows/saved-by-roles.ts` | [`workflows`](config/jobs-and-events.md#workflows) |
 | `notifications/store.ts`, `notifications/history-store.ts`, `notifications/senders.ts` | [`notifications`](config/jobs-and-events.md#notifications) |
 | `files/<name>.ts` | [`files.providers`](config/files.md#filesproviders) |
 
@@ -165,7 +166,7 @@ export default defineUi({ extends: [tasksUi] })
 | `files.trustedHosts` | all kept | |
 | the other keys of `files` | each the app's own; otherwise the last config that sets it | |
 | `writeHooks` | all run, in the same order | |
-| `config/roles.ts`, `auth/authenticate.ts`, `audit/queue.ts`, `hooks/error.ts`, `webhooks/owner-roles.ts`, `notifications/*.ts` | the app's own; otherwise the last extension's | |
+| `config/roles.ts`, `auth/authenticate.ts`, `audit/queue.ts`, `hooks/error.ts`, `webhooks/owner-roles.ts`, `workflows/saved-by-roles.ts`, `notifications/*.ts` | the app's own; otherwise the last extension's | |
 | `auth/hooks.ts`, `auth/mailer.ts` | those of the last folder whose config sets `auth`; otherwise the app's | |
 | every other key (`auth`, `authenticate`, `assistant`, ...) | the app's own; otherwise the last config that sets it | |
 | UI components (exported by name or in `components`), `actions` | all kept | an error naming the name and both configs |

package/skills/protobase/references/reference/data-config.md

@@ -88,7 +88,7 @@ Field and resource names are snake_case by convention, like the columns: they ar
 | `f.timestamp()` | `timestamp`, `timestamptz` | ISO 8601 with offset | an instant, shown on the viewer's clock, in their browser's time zone, which hovering over it names |
 | `f.uuid()` | `uuid` | string | |
 | `f.enum(['a', 'b'])` | Postgres enum, or text with a `CHECK (... IN ...)` | one of the values | |
-| `f.json()` | `json`, `jsonb` | any JSON | |
+| `f.json()` | `json`, `jsonb` | any JSON | nested at most 256 levels deep (each array or object is a level); a deeper value is refused |
 | `f.relation('resource')` | the key column(s) of another resource | its key | `.columns([...])` |
 | `f.currency()` | `text` | ISO 4217 code (`EUR`) | |
 | `f.country()` | `text` | ISO 3166-1 alpha-2 code (`NL`) | |

package/skills/protobase/references/reference/jobs.md

@@ -183,4 +183,4 @@ bun run db:migrate
 
 [`protobase migration`](cli.md#migration) writes what the database lacks, taken from pg-boss's own construction and migration plans for the pinned version, without their `BEGIN` and `COMMIT` and with any `CONCURRENTLY` index build made a plain one, so the file runs in the project's migration transaction. The server never creates or migrates it: `protobase dev` and `protobase serve` read its version at startup and refuse to start while it is missing or behind, naming the command. A database whose jobs schema is newer than the running Protobase is refused too.
 
-pg-boss runs here without what needs a session of its own: no `LISTEN`/`NOTIFY` (a job enqueued in the same process wakes its worker directly, the rest is polled), only transaction-scoped advisory locks, unnamed prepared statements, no index rebuilds and no instance registry. It works through PgBouncer in transaction mode and on PGlite, over the app's own connection pool.
+pg-boss runs here without what needs a session of its own: no `LISTEN`/`NOTIFY` (a job enqueued in the same process wakes its worker directly, the rest is polled), only transaction-scoped advisory locks, unnamed prepared statements, no index rebuilds and no instance registry. It works through PgBouncer in transaction mode, over the app's own connection pool.

package/skills/protobase/references/reference/versioning.md

@@ -44,7 +44,7 @@ Every commit message follows [Conventional Commits](https://www.conventionalcomm
 
 `.github/workflows/release.yml` runs on every push to `main`:
 
-1. The checks of `ci.yml` (`bun run check`, the smoke test on Node, the docs build, the Storybook play tests and the docs check), of the tests and steps the changes since the last `v<version>` tag affect (see What a push checks in `CONTRIBUTING.md`), and commitlint over the pushed commits. The Postgres suite (`bun run test:postgres`, on Postgres and PgBouncer) runs in full as well, whatever changed, beside the other checks. They start at once, and the release waits for them all.
+1. The checks of `ci.yml` (`bun run check`, the smoke test on Node, the docs build, the Storybook play tests and the docs check), of the tests and steps the changes since the last `v<version>` tag affect (see What a push checks in `docs/ci.md`), and commitlint over the pushed commits. The Postgres suite (`bun run test:postgres`, on Postgres and PgBouncer) runs in full as well, whatever changed, beside the other checks. They start at once, and the release waits for them all.
 2. `bun run release` (`scripts/release.mjs`, with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)) computes the next version and its notes from the commits since the last `v<version>` tag, as above, and tags the pushed commit `v<version>`. A squash-merged pull request counts with each commit its body lists as a `* ` item, so one titled `chore` that carries a fix or feature is released; an item an older commit since the tag lists already counts once. It commits nothing and changes no file. Without a fix, feature or breaking change it tags nothing.
 3. The tag is pushed, and the GitHub release of the tag gets the notes.
 4. Beside the checks, a pack job takes the tag `bun run release --dry-run` predicts, and `scripts/stamp-version.mjs` writes its version into every `package.json` and `bun.lock` in the runner, never committed. `scripts/publish.mjs --pack --out` then builds every package to `dist` and packs it with Bun (the private `@protobase/presets` is not published). Once the tag is pushed, npm, under Node, publishes those tarballs with [trusted publishing](https://docs.npmjs.com/trusted-publishers) and provenance (`scripts/publish.mjs --from`); there is no npm token, and only the publish job holds the identity token it needs. A tag other than the version the tarballs were stamped with fails the publish before anything is uploaded, and a run that cut no release packs and publishes nothing.

package/skills/protobase/references/reference/workflows.md

@@ -0,0 +1,243 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/reference/workflows.md: run `bun run docs:skill`, do not edit. -->
+
+# Workflows
+
+Workflows written as state machines in the States Language with JSONata, checked on every save, run step by step on the app's jobs, with every step recorded.
+
+:::caution[Beta]
+Workflows run when they are started through the API or from the app's code. Triggers, sign-in connections to other services, MCP tools for them and a graph editor are not built yet.
+:::
+
+A **workflow** is a graph of steps that the server runs one after another along its edges: fetch something, decide, run a step per item, merge the results, write records, send mail. It is written in the **States Language**, the JSON language of state machines, with **JSONata** as its expression language, in a profile of it that reads every value by name. A language model writes and changes it as easily as a person, and the same document is what the server checks and runs. Each run records every step it takes, with what the step read, gave and logged.
+
+## Turning them on
+
+```ts
+import { defineConfig } from '@protobase/config'
+
+export default defineConfig({ workflows: { secrets: ['TICKETS_TOKEN'] } })
+```
+
+It adds four resources, over a `workflows` schema that [`protobase migration`](cli.md#migration) writes (`NNN_workflows.sql`), and the `workflows.segment` [job](jobs.md) that runs them:
+
+| Resource | |
+| --- | --- |
+| `workflows` | A name, a description and the definition. Each save that changes the definition is checked, and kept as the workflow's next version, saved by the caller. |
+| `workflow_versions` | Every version of every definition as it was saved, with who saved it and when. Read-only. |
+| `workflow_runs` | A run, started by creating it with `workflow_id` and an `input`; it runs the version its workflow had then. Its status, output, error and timing are written by the runner. |
+| `workflow_steps` | Every step of every run. Read-only. |
+
+| `workflows` | |
+| --- | --- |
+| `schema` | The schema of its tables, for a database that has a `workflows` schema already. Default `workflows`. |
+| `secrets` | The environment variables workflows may read, by name. Startup stops when one is unset or shorter than 8 characters. |
+| `allowPrivateAddresses` | Lets the `app:http` step reach private, loopback and link-local addresses, for development and tests. Default false. |
+
+Records steps act as each workflow's last editor, with the roles the project's sign-in gives them now. A project that signs people in otherwise exports its own, `async ({ id, tenant }) => [...]`, as the default of `workflows/saved-by-roles.ts` (`createAdmin` takes it as `workflows.savedByRoles`); without either, startup stops.
+
+## The document
+
+A definition is one JSON document: the workflow's trigger, and the state machine a run runs from `StartAt`. Every state names where the run goes next, and every value in it is JSON; a string written as `{% ... %}` is a JSONata expression, evaluated when the state runs, and keeps its value's type.
+
+```json
+{
+  "trigger": { "record": { "events": ["orders.created"] } },
+  "stateMachine": {
+    "QueryLanguage": "JSONata",
+    "StartAt": "Charge",
+    "States": {
+      "Charge": {
+        "Type": "Task",
+        "Resource": "app:http",
+        "Arguments": {
+          "method": "POST",
+          "url": "https://payments.example.com/charges",
+          "body": { "order_id": "{% $states.context.Execution.Input.after.id %}", "amount": "{% $states.context.Execution.Input.after.total %}" }
+        },
+        "Retry": [{ "ErrorEquals": ["States.ALL"], "IntervalSeconds": 10, "MaxAttempts": 3, "BackoffRate": 2 }],
+        "Catch": [{ "ErrorEquals": ["States.ALL"], "Next": "MarkFailed", "Assign": { "chargeError": "{% $states.errorOutput %}" } }],
+        "End": true
+      },
+      "MarkFailed": {
+        "Type": "Task",
+        "Resource": "app:records.update",
+        "Arguments": { "resource": "orders", "key": "{% $states.context.Execution.Input.after.id %}", "data": { "status": "payment_failed" } },
+        "Next": "TellOps"
+      },
+      "TellOps": {
+        "Type": "Task",
+        "Resource": "app:mail.send",
+        "Arguments": {
+          "to": "ops@example.com",
+          "subject": "{% 'Payment failed for order ' & $states.context.Execution.Input.after.id %}",
+          "text": "{% $chargeError.Cause %}"
+        },
+        "End": true
+      }
+    }
+  }
+}
+```
+
+The document holds no layout: an editor lays the graph out from its edges.
+
+### Triggers
+
+`trigger` holds exactly one of these; its payload is the run's input.
+
+| Trigger | Starts a run | The input holds |
+| --- | --- | --- |
+| `"webhook": {}` | on each POST to the workflow's webhook address | `{ body, headers, query }` |
+| `"schedule": { "cron", "timezone" }` | on a 5-field cron, in an IANA time zone (default `UTC`) | `{ scheduled_at }`, ISO 8601 with the zone's offset |
+| `"mail": { "mailbox" }` | on each mail arriving in that mailbox | `{ from, to, subject, text, html, received_at, attachments }` |
+| `"record": { "events": ["<resource>.<event>"] }` | on each of those record events, such as `deals.created` | `{ event, resource, key, after, before, changed }` |
+| `"manual": {}` | when someone runs the workflow by hand | the input they give |
+
+A save checks a trigger's shape; runs start through the API or the app's code. <gap>A webhook, schedule, mail or record trigger cannot start runs because the triggers are not implemented.</gap>
+
+### Reading values by name
+
+Every value a state reads has a name, so a step can be moved or added without the data around it shifting:
+
+| Name | Holds |
+| --- | --- |
+| `$states.context.Execution.Input` | the run's input, the same in every state |
+| `$states.context.Execution.StartTime` | when the run started, ISO 8601 |
+| `$states.context.Secrets.<NAME>` | the secret of that name, one `workflows.secrets` lists |
+| `$<variable>` | a value an earlier state assigned with `Assign` |
+| `$states.result` | a Task's or Map's result, in its own `Output` and `Assign` |
+| `$states.errorOutput` | the caught error, `{ Error, Cause }`, in a catcher's `Output` and `Assign` |
+| `$states.input` | the item, in the first state of a Map's item processor only |
+
+A state's `Assign` is evaluated with the variables as they were when the state was entered; the new values are seen from the next state on. States inside a Map read the outer variables but may not assign one of the same name.
+
+The save is refused, naming each state and field, when the document does not fit the profile:
+
+- a field does not belong to its state or has the wrong type, or the trigger is not exactly one of the above, with a 5-field cron and a known time zone;
+- a `Next`, `Default` or catcher names no state, a state is never reached, or a state name is used twice, Maps included;
+- a Task names a step type the app does not have, or the state type is not one of Task, Choice, Pass, Map, Wait, Succeed and Fail;
+- an expression does not parse, or reads anything but the names above: the state's input as JSONata's context (a bare field name, `$`, `$$`), `$states.input` outside an item's first state, `$states.context` but for the three reads above, a variable no state that can run before it assigns, or `$eval`;
+- a limit below is passed.
+
+The problem's `problems` lists them as `{ state, field, message }`, where a state inside a Map is named by its path, such as `Each/Total`. The document's JSON Schema is `definitionSchema` of `@protobase/workflows`, and `checkDefinition` runs the whole check.
+
+### States
+
+| Type | |
+| --- | --- |
+| `Task` | Runs a step type, its `Resource`, with its `Arguments`; `TimeoutSeconds`, `Retry` and `Catch`. |
+| `Pass` | Shapes values with `Output` and `Assign`, and goes on. |
+| `Choice` | Goes to the `Next` of the first of its `Choices` whose `Condition` is true, else to its `Default`; with neither it fails with `States.NoChoiceMatched`. A rule may carry its own `Output` and `Assign`. |
+| `Wait` | Waits `Seconds`, or until a `Timestamp` (ISO 8601), as a number or an expression. |
+| `Map` | Runs its `ItemProcessor` once per item of `Items`, at most `MaxConcurrency` at once (0, the default, means the most, 20); its result is the items' outputs in order. |
+| `Succeed` | Ends the run, or the Map item, with its `Output`. |
+| `Fail` | Ends it as failed with its `Error` and `Cause`. |
+
+A state's output is its `Output`, else its result (a Task or Map) or the input it was given. Fields that read a state's input implicitly (`InputPath`, `Parameters`, `ResultPath` and the other fields of the JSONPath language), and `Parallel`, are not part of the profile.
+
+### Errors and retries
+
+A failing Task or Map fails with an error name: a step type's own, such as `Http.Status`, `States.Timeout` when it ran past its timeout, `States.TaskFailed` for any other error it threw, and `States.QueryEvaluationError` for an expression that did not evaluate or ran past its limits. The first retrier whose `ErrorEquals` names it tries the state again after `IntervalSeconds` (default 1), times `BackoffRate` (default 2) for each earlier retry, up to `MaxDelaySeconds`; `MaxAttempts` counts the retries after the first try (default 3, 0 for none). Without `Retry` a failure is not retried. Once no retry is left, the first catcher that names it goes on to its `Next`; without one the run fails. `States.ALL` names every error but `States.DataLimitExceeded` and `States.Runtime`, which end the run even where a retrier or catcher names them.
+
+## Step types
+
+### app:http
+
+One request to a URL built at run time:
+
+| Argument | |
+| --- | --- |
+| `url` | An http or https URL. |
+| `method` | `GET` (default), `POST`, `PUT`, `PATCH` or `DELETE`. |
+| `headers`, `query` | Objects of text values; `query` is added to the URL's query. |
+| `body` | Text is sent as it is, a file value as its bytes with its type, any other value as JSON; a `GET` sends none. |
+| `response` | How the answer's body is read: `json` (default, parsed; empty is `null`), `text`, or `file`, kept as a file of the run. |
+
+The result is `{ status, headers, body }`, without the cookies the answer sets. A status outside 2xx fails the step with `Http.Status`, whose cause names the status and holds at most the first 200 characters of the body, secrets blanked out first; a redirect is never followed. `Http.Network` is a request that got no answer. The step resolves the URL's host when it runs and refuses it with `Http.AddressRefused` unless every address is public, then connects to the very address it checked, so a URL built from a webhook's payload cannot reach the app's own network. It reads at most 10 MiB of the answer's body: a larger one fails the step with `Http.ResponseTooLarge`, rather than being cut short.
+
+### app:records
+
+| Step type | Arguments | Result |
+| --- | --- | --- |
+| `app:records.create` | `resource`, `data`: an object of field values, or a list of them, created in one batch: all or none | the created record, or the list of them |
+| `app:records.update` | `resource`, `key`, `data` | the updated record |
+| `app:records.get` | `resource`, `key` | the record |
+| `app:records.list` | `resource`, optional `filter` (the API's filter syntax), `order_by`, `limit` | `{ records }` |
+
+They go through the app's API as the user who saved the run's version, with the roles that user holds now in the run's tenant, so its access rules, tenant scope, validation and write hooks apply as they do to that user's own requests. Whoever may start a run (`workflow_runs.create`) thus has it do what the workflow's last editor may do; a workflow never does more. When that user holds no role any more, or the version was saved by the app's code, the step fails with `Records.Refused`, as it does for a refusal of the API, its status and message in the cause. A number for a decimal field is written as its text; a file field takes a file value the run keeps.
+
+### app:mail.send
+
+| Argument | |
+| --- | --- |
+| `to` | One address, or a list of at most 50, each one address. |
+| `subject` | One line of text. |
+| `text`, `html` | The body as text, and optionally as HTML. |
+| `attachments` | A list of file values the run keeps, at most 10 MiB together. |
+
+The mail goes from the app's own sender with the app's mailer; a workflow cannot set the sender. The result is `{ message_id }`, the Message-ID the step sets, the same for each try of the step. Without mail the step fails.
+
+### app:piece
+
+`piece`, `action`, `connection` and `props` name an action of a connector and its arguments. A save takes it, and a run fails it with `Piece.Error`. <gap>A piece step cannot run an action because its handler is not implemented.</gap>
+
+### File values
+
+A file value is `{ uri, name, type, size }`, the handle to bytes in the app's storage that the API returns for a file field. `app:http` with `response: "file"` keeps the answer as a file of the run, in the `private` file provider under the run's id; steps take only the files of their own run, so a workflow cannot attach, send or store another file of the app's by naming its URI. <gap>A workflow cannot send or attach a file it read from a record because steps reading the app's other files is not implemented.</gap>
+
+## Runs and their steps
+
+A run starts when it is created, through the API or the admin app, in the same transaction: `POST /api/v1/workflow_runs` with `{ "workflow_id": "...", "input": { ... } }`. The input is at most 1 MiB as JSON and nests at most 64 levels; a larger one is refused with `input-too-large` or `input-too-deep` and no run. From the app's own code, such as a job or a write hook, `startWorkflow(db, { workflow, input, tenant, startedBy })` from `@protobase/server` starts one in `db`'s transaction, so it starts when the caller's writes commit, or not at all. With a `key`, such as `orders:42`, a workflow runs once per key: a start with a key it has a run for already, in this transaction or another, starts nothing and returns that run's id.
+
+Each step is saved as it ends, as a `workflow_steps` record: the state, its type, the scope it ran in (empty for the run itself, `Each.3[0]` for item 0 of the Map `Each` that was step 3), its number, its try, its status (`succeeded`, `retrying`, `caught` or `failed`), its input, output and assigned variables, its logs, when it started and ended and how long it took, its error and cause, and where it goes on to. A run's status is `queued`, `running`, `waiting` (with the time it goes on), `succeeded` with its output, or `failed` with its error and cause.
+
+### Secrets
+
+A workflow reads a secret only by name, `$states.context.Secrets.TICKETS_TOKEN`, and only one the config's `workflows.secrets` lists; the values are never part of the definition. Every value of the listed secrets is blanked out as `[redacted]` wherever it appears in what a run records: a step's input, output, variables, logs, error and cause, and the run's output, error and cause. In a Task's recorded input, every field whose name says it holds a secret, such as `Authorization`, `token` or `apiKey`, is blanked out too. A value an expression computes from a secret, however it changes it, such as `'Basic ' & $base64encode(...)`, is kept whole as `[redacted]`: in a Task's `Arguments` the step type gets the value and the record keeps `[redacted]`; in an `Output`, an `Assign`, a Map's `Items` or a Fail's `Error` and `Cause` the value itself is `[redacted]`, so later states read that. Read a secret in the `Arguments` of the Task that sends it. A secret that comes back changed in a step's result, such as one a server encodes in its answer, is not the value the runner looks for, and is kept as it came. A run's input is kept as its caller gave it, so a secret's value never belongs in it.
+
+## Who may do what
+
+The workflow resources take only [named grants](access.md#resources-that-need-named-grants): a role's wildcard such as `*.read` reaches none of them, since a run reads and sends data as its definition says.
+
+| Grant | |
+| --- | --- |
+| `workflows.create`, `workflows.update`, `workflows.delete` | Make, change and delete workflows. Each save that changes the definition makes the saver the workflow's last editor, whom its records steps act as. |
+| `workflow_runs.create` | Run a workflow, with any input. The API writes only the fields a caller reads, so it goes with `workflow_runs.read`, and the caller must read the workflow too. |
+| `workflows.read`, `workflow_versions.read`, `workflow_runs.read`, `workflow_steps.read` | Read workflows, their versions, runs and steps, the steps' inputs and outputs included. |
+
+```ts
+defineRoles({
+  admin: ['*'],
+  builder: ['workflows.*', 'workflow_versions.read', 'workflow_runs.*', 'workflow_steps.read'],
+})
+```
+
+All four are scoped to the tenant like any resource with `.tenant()`. A run takes its workflow's tenant; a start of another tenant's workflow is refused as one of a workflow that is not there.
+
+## How a run is run
+
+The runner is `@protobase/workflows`, a package with no other Protobase dependency, over a narrow port: where runs and steps are kept (here the `workflows` schema), the queue that runs them (here the app's [jobs](jobs.md)), and the step types.
+
+- A run is run in **segments**, each a `workflows.segment` job whose payload is the run's id alone: one runs the run from where it stands to its next wait, then queues the next. A Wait whose time is still ahead, or a retry's delay, saves its step with the time the run goes on, ends the segment and queues the next one for that time, so a waiting run holds no worker. A segment hands the rest of the run on after a minute of steps.
+- Where a run stands is read from its saved steps. Each step is saved with **one statement**, unique by its scope and number, so a second segment of the same run saves nothing and stops.
+- A worker that stops or dies mid-step leaves that step unsaved: its job is tried again and takes the run up from its last saved step, so a saved step never runs again, and the step that was in progress runs **at least once**. A step whose effect happened before its result was saved, such as a request that was sent, happens again. Every try of a step gets the same idempotency key, for a step type whose receiver dedupes by it, and `app:mail.send` makes it the mail's Message-ID. A job whose worker died is tried again once its timeout, 10 minutes, has passed.
+- A Map's items run in the segment that reaches them, each item's steps saved under its own scope; an item that waits ends the segment once the others running settle, and the next segment takes each item up where it stands. A Map's `Items` is evaluated again by a segment that takes up an unfinished Map.
+- JSONata runs in the server's process under a time and a depth limit per expression; it reaches no file, network or code of the app.
+
+Every limit fails closed: a run or step that passes one fails, rather than going on with less.
+
+| Limit | |
+| --- | --- |
+| A definition | 256 KiB as JSON, 100 states, Maps included; an expression 4,096 characters. |
+| An expression's evaluation | 1 second, and 300 levels deep; beyond, `States.QueryEvaluationError`. |
+| A Task's `TimeoutSeconds` | 300 by default, and at most. |
+| A retrier's `MaxAttempts` | 19. |
+| The wait before a retry | 1 day, however `BackoffRate` grows it. |
+| A Map's items | 10,000; beyond, the Map fails with `States.DataLimitExceeded` before any item runs. |
+| A Map's `MaxConcurrency` | 20. |
+| Steps of one run, every try and item counted | 50,000; beyond, the run fails with `States.Runtime`. |
+| The input, output and variables a step saves | 1 MiB each, as JSON; beyond, the step fails with `States.DataLimitExceeded`. |
+| A step's logs | 100 lines of 1,000 characters; more lines are left out with a last line saying how many. |
+| A run's input | 1 MiB as JSON, 64 levels deep. |
+| An answer `app:http` reads, a file a run keeps | 10 MiB. |
+| A Wait | 366 days, by `Seconds` or `Timestamp`. |