@protobase/workflows 0.0.0-stage → 0.68.0

package/dist/plugin/type-catalog.d.ts

@@ -0,0 +1,19 @@
+import { TypeEntry } from "./type-list.js";
+//#region src/plugin/type-catalog.d.ts
+/** A type as a model or the editor reads it: its declaration as its plugin gives it, with whether this app can run it. */
+export type CatalogEntry = Omit<TypeEntry, 'kind' | 'plugin'> & {
+  kind: TypeEntry['kind'] | 'manual';
+};
+/**
+ * What `list_workflow_types` answers and the editor reads: every step type a Task names as its `Resource` and every
+ * trigger a definition's `trigger` holds as `{ "<id>": <input> }`, built-in and plugin types alike, each with its JSON
+ * Schemas.
+ */
+export declare const typeCatalog: (types: readonly TypeEntry[]) => TypeCatalog;
+/** The app's types, `manual` first among the triggers, as `typeCatalog` lists them. */
+export type TypeCatalog = {
+  step_types: CatalogEntry[];
+  triggers: CatalogEntry[];
+  note: string;
+};
+//#endregion

package/dist/plugin/type-catalog.js

@@ -0,0 +1,26 @@
+//#region src/plugin/type-catalog.ts
+const entry = ({ plugin: _, ...type }) => type;
+/** `manual`, the trigger of a workflow that runs only when someone starts it. */
+const manual = {
+	id: "manual",
+	kind: "manual",
+	label: "By hand",
+	description: "Runs when someone starts it, such as with run_workflow, with the input they give.",
+	input: {
+		type: "object",
+		additionalProperties: false
+	},
+	available: true
+};
+/**
+* What `list_workflow_types` answers and the editor reads: every step type a Task names as its `Resource` and every
+* trigger a definition's `trigger` holds as `{ "<id>": <input> }`, built-in and plugin types alike, each with its JSON
+* Schemas.
+*/
+const typeCatalog = (types) => ({
+	step_types: types.filter((type) => type.kind === "step").map(entry),
+	triggers: [manual, ...types.filter((type) => type.kind !== "step").map(entry)],
+	note: "A definition holds its trigger as { \"<id>\": <input> }, such as { \"app:record\": { \"resource\": \"orders\" } }. A type with available false cannot be saved here; its reason says why. A trigger other than manual starts runs only while its workflow is enabled, its enabled_version set; run_workflow starts a run of any workflow, enabled or not, so a manual workflow needs no enabled_version."
+});
+//#endregion
+export { typeCatalog };

package/dist/plugin/type-list.d.ts

@@ -0,0 +1,26 @@
+import { JsonSchema } from "./context.js";
+import { ConnectionDeclaration, Plugin, TriggerType } from "./types.js";
+//#region src/plugin/type-list.d.ts
+/** A type as the MCP tools and the editor list it: built-in and plugin types alike. */
+export type TypeEntry = {
+  /** `<plugin>:<key>`: a Task's `Resource`, or the key of a definition's `trigger`. */
+  id: string;
+  kind: 'step' | TriggerType['kind'];
+  plugin: string;
+  label: string;
+  description: string;
+  input: JsonSchema;
+  output?: JsonSchema;
+  errors?: Record<string, string>;
+  connection?: {
+    name: string;
+  } & ConnectionDeclaration;
+  /** False when this app cannot run it, with the reason; a definition that uses it is not saved. */
+  available: boolean;
+  reason?: string;
+};
+/** Why the app cannot run a type, or undefined when it can. */
+export type Unavailable = (type: Omit<TypeEntry, 'available'>) => string | undefined;
+/** Every type of `plugins`, steps first, each marked available or not by `unavailable`. */
+export declare const typeList: (plugins: readonly Plugin[], unavailable: Unavailable) => TypeEntry[];
+//#endregion

package/dist/plugin/type-list.js

@@ -0,0 +1,26 @@
+//#region src/plugin/type-list.ts
+const entry = (plugin, key, type) => ({
+	id: `${plugin.name}:${key}`,
+	kind: "kind" in type ? type.kind : "step",
+	plugin: plugin.name,
+	label: type.label,
+	description: type.description,
+	input: type.input,
+	...type.output && { output: type.output },
+	..."errors" in type && type.errors && { errors: Object.fromEntries(Object.entries(type.errors).map(([name, text]) => [`${type.errorPrefix ?? "Step"}.${name}`, text])) },
+	...type.connection !== void 0 && { connection: {
+		name: type.connection,
+		...plugin.connections[type.connection]
+	} }
+});
+/** Every type of `plugins`, steps first, each marked available or not by `unavailable`. */
+const typeList = (plugins, unavailable) => plugins.flatMap((plugin) => [...Object.entries(plugin.steps ?? {}), ...Object.entries(plugin.triggers ?? {})].map(([key, type]) => entry(plugin, key, type))).map((type) => {
+	const reason = unavailable(type);
+	return {
+		...type,
+		available: reason === void 0,
+		...reason !== void 0 && { reason }
+	};
+});
+//#endregion
+export { typeList };

package/dist/plugin/types.d.ts

@@ -0,0 +1,123 @@
+import { JsonSchema, PluginConnection, PluginFetch, StepContext } from "./context.js";
+//#region src/plugin/types.d.ts
+/** What a type shows in the type list the MCP tools and the editor read. */
+type Described = {
+  label: string;
+  description: string;
+  /** What it takes, checked before it runs. */
+  input: JsonSchema;
+  /** What it gives: a step's result, or a trigger's run input. */
+  output?: JsonSchema;
+  /** The name of a connection the plugin declares, which it signs in with. */
+  connection?: string;
+};
+/** A step type, which a Task names as `<plugin>:<key>` in its `Resource`. */
+export type StepType = Described & {
+  /** The errors it fails with, by name, as `<Prefix>.<Name>`, each with what it means. */
+  errors?: Record<string, string>;
+  /** The prefix of its error names, such as `Http`; an input that does not fit fails as `<prefix>.InvalidArguments`. Default `Step`. */
+  errorPrefix?: string;
+  run: (context: StepContext) => Promise<unknown>;
+};
+/** What every trigger type has: its description, and a check of its input beyond its schema, such as a cron's fields. */
+type TriggerBase = Described & {
+  check?: (input: Record<string, unknown>) => {
+    field?: string;
+    message: string;
+  }[];
+};
+/** What a trigger's hooks get: its checked input, its connection, and the guarded `fetch`. */
+export type TriggerContext = {
+  input: Record<string, unknown>;
+  connection: PluginConnection | undefined;
+  fetch: PluginFetch;
+  signal: AbortSignal;
+};
+/**
+ * A trigger that starts one run per record that becomes ready: `when` is a filter on `resource` in the filter language,
+ * whose `<timestamp field> <= now() - <duration>` terms make the start wait until that time. A record starts once per
+ * ready key: its record key and the values of the `key` fields.
+ */
+export type ReadyTrigger = TriggerBase & {
+  kind: 'ready';
+  ready: (input: Record<string, unknown>) => {
+    resource: string;
+    when?: string;
+    key?: string[];
+  };
+};
+/** One new thing a poll or a webhook call found: `key` is unique for the trigger, `data` becomes the run's input. */
+export type TriggerItem = {
+  key: string;
+  data: unknown;
+};
+/** A trigger that asks a service for new items on a schedule. */
+export type PollingTrigger = TriggerBase & {
+  kind: 'polling';
+  /** A duration such as `1 minute`, or a cron in an IANA time zone. */
+  every: string | {
+    cron: string;
+    timezone?: string;
+  };
+  /** The most items one poll returns, at most 100. */
+  limit?: number;
+  start: (context: TriggerContext) => Promise<unknown>;
+  /** Items after `cursor`, and the next cursor, which must move forward. */
+  poll: (context: TriggerContext & {
+    cursor: unknown;
+    store: unknown;
+    limit: number;
+  }) => Promise<{
+    items: TriggerItem[];
+    cursor: unknown;
+    store?: unknown;
+  }>;
+};
+/** A trigger that the app's webhook URL starts, after the route checked the call's signature. */
+export type WebhookTrigger = TriggerBase & {
+  kind: 'webhook';
+  /** Registers the URL with the service, returning what `unsubscribe` and `renew` need. */
+  subscribe?: (context: TriggerContext & {
+    url: string;
+  }) => Promise<unknown>;
+  unsubscribe?: (context: TriggerContext & {
+    state: unknown;
+  }) => Promise<void>;
+  renew?: (context: TriggerContext & {
+    state: unknown;
+  }) => Promise<unknown>;
+  renewEvery?: string;
+  receive: (context: {
+    request: Request;
+    input: Record<string, unknown>;
+  }) => Promise<{
+    items: TriggerItem[];
+    response?: Response;
+  }>;
+};
+export type TriggerType = ReadyTrigger | PollingTrigger | WebhookTrigger;
+/** A sign-in a plugin's types use: one of the app's sign-in providers, or an OAuth provider of its own. */
+export type ConnectionDeclaration = {
+  label: string;
+  scopes?: string[];
+} & ({
+  signIn: string;
+} | {
+  oauth: {
+    authorization_url: string;
+    token_url: string;
+    user_info_url?: string;
+    revocation_url?: string;
+    pkce?: boolean;
+  };
+});
+/** A workflow plugin: the trigger and step types it adds, and the sign-ins they use. */
+export type Plugin = {
+  /** Its types are named `<name>:<key>`. */
+  name: string;
+  label: string;
+  connections?: Record<string, ConnectionDeclaration>;
+  triggers?: Record<string, TriggerType>;
+  steps?: Record<string, StepType>;
+};
+//#endregion

package/dist/run/context.d.ts

@@ -0,0 +1,18 @@
+//#region src/run/context.d.ts
+/** A scope that cannot go on in this segment: it waits until a time, or the segment's time is up. */
+export type Paused = {
+  kind: 'blocked';
+  until: Date;
+} | {
+  kind: 'yielded';
+};
+/** How a scope ended in this segment. */
+export type ScopeOutcome = {
+  kind: 'ended';
+  output: unknown;
+} | {
+  kind: 'failed';
+  error: string;
+  cause: string;
+} | Paused;
+//#endregion

package/dist/run/errors.d.ts

@@ -0,0 +1,20 @@
+//#region src/run/errors.d.ts
+/**
+ * A step's failure by name, as `Catch` and `Retry` match it in `ErrorEquals`: a step type throws one with its own
+ * names (such as `Http.Status`); any other error a step throws counts as `States.TaskFailed`.
+ */
+declare const brand: unique symbol;
+export declare class StepError extends Error {
+  readonly error: string;
+  readonly reason: string;
+  name: string;
+  readonly [brand] = true;
+  constructor(error: string, reason: string);
+  static [Symbol.hasInstance](value: unknown): boolean;
+}
+/** The error and cause a failed step records, which `$states.errorOutput` holds in a catcher. */
+export type ErrorOutput = {
+  Error: string;
+  Cause: string;
+};
+//#endregion

package/dist/run/errors.js

@@ -0,0 +1,39 @@
+//#region src/run/errors.ts
+/**
+* A step's failure by name, as `Catch` and `Retry` match it in `ErrorEquals`: a step type throws one with its own
+* names (such as `Http.Status`); any other error a step throws counts as `States.TaskFailed`.
+*/
+const brand = Symbol.for("protobase.workflows.StepError");
+var StepError = class extends Error {
+	error;
+	reason;
+	name = "StepError";
+	[brand] = true;
+	constructor(error, reason) {
+		super(`${error}: ${reason}`);
+		this.error = error;
+		this.reason = reason;
+	}
+	static [Symbol.hasInstance](value) {
+		return typeof value === "object" && value !== null && value[brand] === true;
+	}
+};
+const errorOutput = (thrown) => {
+	if (thrown instanceof StepError) return {
+		Error: thrown.error,
+		Cause: thrown.reason
+	};
+	return {
+		Error: "States.TaskFailed",
+		Cause: thrown instanceof Error ? thrown.message : String(thrown)
+	};
+};
+const terminal = /* @__PURE__ */ new Set(["States.Runtime", "States.DataLimitExceeded"]);
+/** Whether `ErrorEquals` names the error, or `States.ALL` does, for an error that does not end the run. */
+const matches = (names, error) => !terminal.has(error) && (names.includes(error) || names.includes("States.ALL"));
+/** Thrown when another segment saved a step first: this one stops, since the run went on without it. */
+var SupersededError = class extends Error {
+	name = "SupersededError";
+};
+//#endregion
+export { StepError, SupersededError, errorOutput, matches };

package/dist/run/evaluate.js

@@ -0,0 +1,59 @@
+import { compile, expressionSource, isJsonataError, parse } from "../definition/expressions.js";
+import { expressionReads } from "../definition/reads.js";
+import { StepError } from "./errors.js";
+//#region src/run/evaluate.ts
+const evaluated = async (source, bindings, field) => {
+	try {
+		return await compile(source).evaluate(void 0, bindings);
+	} catch (error) {
+		if (!isJsonataError(error)) throw error;
+		throw new StepError("States.QueryEvaluationError", `${field}: ${error.message}`);
+	}
+};
+/**
+* Whether an expression reads one of the app's secrets, from its syntax tree, so no spelling (a quoted name, a comment)
+* hides one. The check lets a secret be read only as `$states.context.Secrets.<NAME>`; a read of `$states` or its
+* `context` whole counts too, and so does an expression that does not parse, rather than being trusted.
+*/
+const readsSecret = (source) => {
+	const parsed = parse(source);
+	if ("error" in parsed) return true;
+	return expressionReads(parsed.expression).states.some(([field, next]) => field === void 0 || field === "context" && (next === void 0 || next === "Secrets"));
+};
+/** What a value computed from a secret is kept as, however the expression changed it, such as encoded or cut apart. */
+const secretValue = "[redacted]";
+/**
+* A template with each `{% ... %}` replaced by its value; an evaluation that fails is `States.QueryEvaluationError`.
+* With `kept`, for a value the run keeps (an Output, a variable, a Map's items, a Fail's error), an expression that
+* reads a secret gives `[redacted]`: what it computes is never saved, and later states read what was saved.
+*/
+const evaluateTemplate = async (template, bindings, field, kept = false) => {
+	const source = expressionSource(template);
+	if (source !== void 0) return kept && readsSecret(source) ? secretValue : evaluated(source, bindings, field);
+	if (Array.isArray(template)) return Promise.all(template.map((item, index) => evaluateTemplate(item, bindings, `${field}[${index}]`, kept)));
+	if (typeof template === "object" && template !== null) {
+		const entries = await Promise.all(Object.entries(template).map(async ([key, value]) => [key, await evaluateTemplate(value, bindings, `${field}.${key}`, kept)]));
+		return Object.fromEntries(entries.filter(([, value]) => value !== void 0));
+	}
+	return template;
+};
+/** A value the run keeps: an Output, a Map's items or a Fail's error, an expression reading a secret kept as `[redacted]`. */
+const evaluateKept = (template, bindings, field) => evaluateTemplate(template, bindings, field, true);
+/** The values of an `Assign`, each by its name, an expression reading a secret kept as `[redacted]`. */
+const evaluateAssign = async (assign, bindings, field = "Assign") => {
+	if (!assign) return {};
+	return await evaluateKept(assign, bindings, field);
+};
+/**
+* A Task's arguments as its step records them: each one an expression computed from a secret is `[redacted]`, while
+* the step type is given the value itself.
+*/
+const recordedArguments = (template, args) => {
+	const source = expressionSource(template);
+	if (source !== void 0) return readsSecret(source) ? secretValue : args;
+	if (Array.isArray(template) && Array.isArray(args)) return args.map((item, index) => recordedArguments(template[index], item));
+	if (typeof template === "object" && template !== null && typeof args === "object" && args !== null && !Array.isArray(args)) return Object.fromEntries(Object.entries(args).map(([key, value]) => [key, recordedArguments(template[key], value)]));
+	return args;
+};
+//#endregion
+export { evaluateAssign, evaluateKept, evaluateTemplate, readsSecret, recordedArguments, secretValue };

package/dist/run/fan-out.js

@@ -0,0 +1,39 @@
+//#region src/run/fan-out.ts
+/**
+* Runs the scopes, at most `concurrency` at once. Once one fails, throws, or the segment's time is up, no more start and
+* the running ones settle, so none runs on after the segment ends; one that waits leaves the others running, and the
+* whole waits for the earliest time. A scope's error is thrown once all have settled.
+*/
+const fanOut = async (scopes, concurrency) => {
+	const outcomes = new Array(scopes.length);
+	let next = 0;
+	let stop = false;
+	const lane = async () => {
+		while (!stop && next < scopes.length) {
+			const index = next++;
+			const outcome = await scopes[index]().catch((error) => {
+				stop = true;
+				throw error;
+			});
+			outcomes[index] = outcome;
+			if (outcome.kind === "failed" || outcome.kind === "yielded") stop = true;
+		}
+	};
+	const thrown = (await Promise.allSettled(Array.from({ length: Math.min(concurrency, scopes.length) }, lane))).find((settled) => settled.status === "rejected");
+	if (thrown) throw thrown.reason;
+	const settled = outcomes.filter(Boolean);
+	const failed = settled.find((outcome) => outcome.kind === "failed");
+	if (failed) return failed;
+	if (settled.some((outcome) => outcome.kind === "yielded") || settled.length < scopes.length) return { kind: "yielded" };
+	const waits = settled.flatMap((outcome) => outcome.kind === "blocked" ? [outcome.until.getTime()] : []);
+	if (waits.length > 0) return {
+		kind: "blocked",
+		until: new Date(Math.min(...waits))
+	};
+	return {
+		kind: "ended",
+		outputs: settled.map((outcome) => outcome.output)
+	};
+};
+//#endregion
+export { fanOut };

package/dist/run/json-bytes.js

@@ -0,0 +1,5 @@
+//#region src/run/json-bytes.ts
+/** A value's size as JSON in UTF-8 bytes; nothing (`undefined`) is 0. */
+const jsonBytes = (value) => value === void 0 ? 0 : new TextEncoder().encode(JSON.stringify(value)).length;
+//#endregion
+export { jsonBytes };

package/dist/run/port.d.ts

@@ -0,0 +1,105 @@
+import { Definition } from "../definition/types.js";
+//#region src/run/port.d.ts
+/**
+ * How a step ended: `succeeded`, `retrying` (it failed and a retrier tries it again), `caught` (it failed and a
+ * catcher went on elsewhere) or `failed` (nothing caught it, so its scope failed).
+ */
+export type StepStatus = 'succeeded' | 'retrying' | 'caught' | 'failed';
+/** What the runner reads of a saved step to know where its scope stands. */
+export type SavedStep = {
+  /** The scope the step ran in: `''` for the run itself, `Each.3[0]` for item 0 of the Map `Each` that was step 3. */
+  scope: string;
+  /** The step's number within its scope, from 0: with the scope, the step's key, saved once. */
+  seq: number;
+  state: string;
+  status: StepStatus;
+  attempt: number;
+  output?: unknown;
+  /** The variables the step assigned. */
+  assigned?: Record<string, unknown>;
+  /** The state its scope goes on to; `null` when the scope ended or failed, or for a try that is retried. */
+  next: string | null;
+  /** The next state may not run before this time: after a Wait, or a retry's delay. */
+  resumeAt?: Date | null;
+  error?: string | null;
+  cause?: string | null;
+};
+export type StepLog = {
+  at: string;
+  message: string;
+};
+/** All a step records: what the runner reads, and its type, input, logs and timing, with every secret redacted. */
+export type StepRecord = SavedStep & {
+  type: string;
+  input?: unknown;
+  logs: StepLog[];
+  startedAt: Date;
+  finishedAt: Date;
+};
+/** What a step type's handler gets beside its arguments. */
+export type TaskContext = {
+  /** The run's id: files a step stores for the run are kept under it. */
+  runId: string;
+  /** Aborted when the step's timeout passes, or when the worker stops. */
+  signal: AbortSignal;
+  /** The same for every retry of one visit of this step in this run, so a receiver that dedupes by it sees a repeated try once; a later visit gets a new one. */
+  idempotencyKey: string;
+  /** Adds a line to the step's logs, with the app's secrets blanked out; a step keeps `limits.logLines` lines. */
+  log: (message: string) => void;
+  /**
+   * The text with the app's secrets blanked out. The runner blanks them out of all a step records; a step that cuts a
+   * text short, such as an answer's body in an error, blanks it first, so the cut leaves no part of a secret.
+   */
+  redact: (text: string) => string;
+};
+/**
+ * A step type, which a Task names as its `Resource`: it takes the Task's evaluated `Arguments` and returns its result.
+ * It throws a `StepError` to fail with an error name of its own; any other error is `States.TaskFailed`.
+ */
+export type TaskHandler = (args: unknown, context: TaskContext) => Promise<unknown>;
+/** The interpreter's back end: the step types by the name a Task's `Resource` gives. */
+export type TaskHandlers = Readonly<Record<string, TaskHandler>>;
+/** A run as the runner loads it: its pinned definition, its input and when it started. */
+export type LoadedRun = {
+  id: string;
+  definition: Definition;
+  input: unknown;
+  status: RunStatus;
+  startedAt: Date;
+};
+export type RunStatus = 'queued' | 'running' | 'waiting' | 'succeeded' | 'failed';
+/** What changes on a run as a segment ends. */
+export type RunChange = {
+  status: 'running';
+} | {
+  status: 'waiting';
+  resumeAt: Date;
+} | {
+  status: 'succeeded';
+  output: unknown;
+} | {
+  status: 'failed';
+  error: string;
+  cause: string;
+};
+/**
+ * Where runs and their steps are kept, in the database or transaction `Db` the caller gives: the first part of the
+ * runner's port.
+ */
+export type RunStore<Db> = {
+  load(db: Db, runId: string): Promise<LoadedRun | undefined>;
+  /** Every step the run saved, in each scope's order; the record's input and logs are not needed. */
+  steps(db: Db, runId: string): Promise<SavedStep[]>;
+  /**
+   * Saves steps in one guarded statement: false when any of their scopes and seqs is taken already, and those are left
+   * as the other segment saved them.
+   */
+  save(db: Db, runId: string, steps: readonly StepRecord[]): Promise<boolean>;
+  /** Changes the run unless it has ended already. */
+  update(db: Db, runId: string, change: RunChange): Promise<void>;
+};
+/** The jobs queue: the second part of the port, which runs a segment of the run at `at`, or as soon as it can. */
+export type SegmentQueue<Db> = {
+  schedule(db: Db, runId: string, at?: Date): Promise<void>;
+};
+//#endregion

package/dist/run/position.js

@@ -0,0 +1,54 @@
+//#region src/run/position.ts
+const startPosition = (machine, input) => ({
+	kind: "at",
+	seq: 0,
+	state: machine.StartAt,
+	input,
+	variables: {},
+	attempt: 1,
+	failures: []
+});
+/** The position after a saved step. */
+const advance = (position, step) => {
+	if (position.kind !== "at") return position;
+	const seq = step.seq + 1;
+	const variables = {
+		...position.variables,
+		...step.assigned
+	};
+	if (step.status === "failed") return {
+		kind: "failed",
+		seq,
+		error: step.error ?? "States.Runtime",
+		cause: step.cause ?? ""
+	};
+	if (step.status === "retrying") return {
+		...position,
+		seq,
+		variables,
+		attempt: position.attempt + 1,
+		failures: [...position.failures, step.error ?? ""],
+		...step.resumeAt && { resumeAt: step.resumeAt }
+	};
+	const output = step.output === void 0 ? null : step.output;
+	if (step.next === null) return {
+		kind: "ended",
+		seq,
+		output,
+		variables
+	};
+	return {
+		kind: "at",
+		seq,
+		state: step.next,
+		input: output,
+		variables,
+		attempt: 1,
+		failures: [],
+		...step.resumeAt && { resumeAt: step.resumeAt }
+	};
+};
+/** Where a scope stands after the steps it saved, in their order. */
+const foldPosition = (machine, input, steps) => steps.reduce(advance, startPosition(machine, input));
+//#endregion
+export { advance, foldPosition, startPosition };

package/dist/run/recovery.js

@@ -0,0 +1,76 @@
+import { limits } from "../limits.js";
+import { StepError, matches } from "./errors.js";
+import { evaluateAssign, evaluateKept } from "./evaluate.js";
+//#region src/run/recovery.ts
+/**
+* The wait before a retry: `IntervalSeconds` times `BackoffRate` for each earlier retry, up to `MaxDelaySeconds`, and
+* never more than `limits.retryDelaySeconds`, which is also the cap when the retrier names none.
+*/
+const retryDelaySeconds = (retrier, retries) => {
+	const delay = (retrier.IntervalSeconds ?? 1) * (retrier.BackoffRate ?? 2) ** retries;
+	return Math.min(delay, retrier.MaxDelaySeconds ?? limits.retryDelaySeconds);
+};
+const caught = async (catcher, failure, bindings, logs) => {
+	const after = {
+		...bindings,
+		states: {
+			...bindings.states,
+			errorOutput: failure
+		}
+	};
+	const output = catcher.Output === void 0 ? failure : await evaluateKept(catcher.Output, after, "Output");
+	return {
+		kind: "step",
+		status: "caught",
+		next: catcher.Next,
+		output,
+		assigned: await evaluateAssign(catcher.Assign, after),
+		error: failure.Error,
+		cause: failure.Cause,
+		logs
+	};
+};
+/**
+* What a failed Task or Map does: the first retrier that names its error tries it again after its delay
+* while it has tries left; else the first catcher that names it goes on to its `Next`; else the state fails.
+*/
+const recover = async (state, position, failure, bindings, now, logs) => {
+	const retriers = state.Retry ?? [];
+	const retrierOf = (error) => retriers.findIndex((retrier) => matches(retrier.ErrorEquals, error));
+	const index = retrierOf(failure.Error);
+	if (index >= 0) {
+		const retrier = retriers[index];
+		const retries = position.failures.filter((error) => retrierOf(error) === index).length;
+		if (retries < (retrier.MaxAttempts ?? 3)) return {
+			kind: "step",
+			status: "retrying",
+			next: null,
+			resumeAt: new Date(now.getTime() + retryDelaySeconds(retrier, retries) * 1e3),
+			error: failure.Error,
+			cause: failure.Cause,
+			logs
+		};
+	}
+	const catcher = (state.Catch ?? []).find((candidate) => matches(candidate.ErrorEquals, failure.Error));
+	if (!catcher) return {
+		kind: "step",
+		status: "failed",
+		next: null,
+		error: failure.Error,
+		cause: failure.Cause,
+		logs
+	};
+	return caught(catcher, failure, bindings, logs).catch((error) => {
+		if (!(error instanceof StepError)) throw error;
+		return {
+			kind: "step",
+			status: "failed",
+			next: null,
+			error: error.error,
+			cause: error.reason,
+			logs
+		};
+	});
+};
+//#endregion
+export { recover, retryDelaySeconds };

package/dist/run/redact.d.ts

@@ -0,0 +1,16 @@
+//#region src/run/redact.d.ts
+/** A copy of a value with each field whose name says it holds a secret, such as `Authorization` or `apiKey`, replaced. */
+export declare const redacted: (value: unknown) => unknown;
+/** Secret values shorter than this are refused, so blanking them never blanks ordinary text. */
+export declare const shortestSecret = 8;
+/** Replaces every secret value inside a text, and inside every text of a value, by `[redacted]`. */
+export type Redactor = {
+  text: (text: string) => string;
+  value: <T>(value: T) => T;
+};
+/**
+ * The redactor of the app's secret values, wherever they appear inside a text, such as `Bearer <token>` or a token in
+ * a URL's query; the longest first, so a secret inside another is blanked whole.
+ */
+export declare const secretRedactor: (secrets: readonly string[]) => Redactor;
+//#endregion