@protobase/workflows 0.0.0-stage → 0.68.0

package/dist/run/redact.js

@@ -0,0 +1,39 @@
+//#region src/run/redact.ts
+const secretKey = /^pass$|pass(word|phrase|code|wd)|secret|token|authorization|api[-_]?key|cookie|credential|private[-_]?key|signature/i;
+/** A copy of a value with each field whose name says it holds a secret, such as `Authorization` or `apiKey`, replaced. */
+const redacted = (value) => {
+	if (Array.isArray(value)) return value.map(redacted);
+	if (typeof value !== "object" || value === null) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, secretKey.test(key) ? "[redacted]" : redacted(item)]));
+};
+/** Secret values shorter than this are refused, so blanking them never blanks ordinary text. */
+const shortestSecret = 8;
+/**
+* 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.
+*/
+const secretRedactor = (secrets) => {
+	if (secrets.find((secret) => secret.length < 8) !== void 0) throw new Error(`A secret workflows read is shorter than 8 characters, too short to blank out of what runs record`);
+	const ordered = [...new Set(secrets)].sort((a, b) => b.length - a.length);
+	const text = (input) => ordered.reduce((result, secret) => result.replaceAll(secret, "[redacted]"), input);
+	const value = (input) => {
+		if (ordered.length === 0) return input;
+		if (typeof input === "string") return text(input);
+		if (Array.isArray(input)) return input.map(value);
+		if (typeof input !== "object" || input === null || input instanceof Date) return input;
+		const kept = {};
+		for (const [key, item] of Object.entries(input)) {
+			const blanked = text(key);
+			let name = blanked;
+			for (let count = 2; Object.hasOwn(kept, name); count++) name = `${blanked} (${count})`;
+			kept[name] = value(item);
+		}
+		return kept;
+	};
+	return {
+		text,
+		value
+	};
+};
+//#endregion
+export { redacted, secretRedactor, shortestSecret };

package/dist/run/rerun.d.ts

@@ -0,0 +1,18 @@
+import { Machine } from "../definition/types.js";
+import { SavedStep } from "./port.js";
+//#region src/run/rerun.d.ts
+/** What a re-run reads of a failed run's step to know whether to keep it. */
+export type EarlierStep = Pick<SavedStep, 'scope' | 'seq' | 'state' | 'status' | 'next'>;
+/**
+ * The steps of a failed run that a re-run of it keeps, to run on from where they leave it with `machine`, the workflow's
+ * version now: every step but, in each scope, the try that failed it and that state's retried tries before it, so the
+ * failed state runs again from its first try. A finished Map's items are kept as they ran; the items of a Map that runs
+ * again are kept where they stand, each without its own failed try, and those of a Map's earlier tries are not.
+ * Returns the problem instead when a scope would go on at a state the version does not have.
+ */
+export declare const rerunSteps: <S extends EarlierStep>(machine: Machine, steps: readonly S[]) => {
+  steps: S[];
+} | {
+  problem: string;
+};
+//#endregion

package/dist/run/rerun.js

@@ -0,0 +1,62 @@
+//#region src/run/rerun.ts
+const itemOf = (scope) => {
+	const slash = scope.lastIndexOf("/");
+	const match = /^(.*)\.(\d+)\[\d+\]$/.exec(scope.slice(slash + 1));
+	if (!match) throw new Error(`"${scope}" is not the scope of a Map item`);
+	return {
+		parent: slash < 0 ? "" : scope.slice(0, slash),
+		map: decodeURIComponent(match[1]),
+		seq: Number(match[2])
+	};
+};
+const withoutFailure = (steps) => {
+	if (steps.at(-1)?.status !== "failed") return [...steps];
+	const failed = steps.at(-1);
+	let end = steps.length - 1;
+	while (end > 0 && steps[end - 1].status === "retrying" && steps[end - 1].state === failed.state) end--;
+	return steps.slice(0, end);
+};
+/**
+* The steps of a failed run that a re-run of it keeps, to run on from where they leave it with `machine`, the workflow's
+* version now: every step but, in each scope, the try that failed it and that state's retried tries before it, so the
+* failed state runs again from its first try. A finished Map's items are kept as they ran; the items of a Map that runs
+* again are kept where they stand, each without its own failed try, and those of a Map's earlier tries are not.
+* Returns the problem instead when a scope would go on at a state the version does not have.
+*/
+const rerunSteps = (machine, steps) => {
+	const byScope = /* @__PURE__ */ new Map();
+	for (const step of [...steps].sort((a, b) => a.seq - b.seq)) byScope.set(step.scope, [...byScope.get(step.scope) ?? [], step]);
+	const children = /* @__PURE__ */ new Map();
+	for (const scope of byScope.keys()) {
+		if (scope === "") continue;
+		const { parent } = itemOf(scope);
+		children.set(parent, [...children.get(parent) ?? [], scope]);
+	}
+	const kept = [];
+	const keepAll = (scope) => {
+		kept.push(...byScope.get(scope) ?? []);
+		for (const child of children.get(scope) ?? []) keepAll(child);
+	};
+	const keepFrom = (scope, inner) => {
+		const own = withoutFailure(byScope.get(scope) ?? []);
+		kept.push(...own);
+		const last = own.at(-1);
+		const at = last === void 0 ? inner.StartAt : last.status === "retrying" ? last.state : last.next;
+		if (at !== null && !Object.hasOwn(inner.States, at)) return `The run goes on at state "${at}"${scope ? ` in ${scope}` : ""}, which the workflow no longer has`;
+		const state = at === null ? void 0 : inner.States[at];
+		const ran = new Set(own.map((step) => step.seq));
+		const next = last === void 0 ? 0 : last.seq + 1;
+		for (const child of children.get(scope) ?? []) {
+			const item = itemOf(child);
+			if (ran.has(item.seq)) keepAll(child);
+			else if (item.seq === next && item.map === at && state?.Type === "Map") {
+				const problem = keepFrom(child, state.ItemProcessor);
+				if (problem) return problem;
+			}
+		}
+	};
+	const problem = keepFrom("", machine);
+	return problem ? { problem } : { steps: kept };
+};
+//#endregion
+export { rerunSteps };

package/dist/run/result-states.js

@@ -0,0 +1,115 @@
+import { limits } from "../limits.js";
+import { StepError, errorOutput } from "./errors.js";
+import { redacted } from "./redact.js";
+import { jsonBytes } from "./json-bytes.js";
+import { evaluateAssign, evaluateKept, evaluateTemplate, recordedArguments } from "./evaluate.js";
+import { fanOut } from "./fan-out.js";
+import { recover } from "./recovery.js";
+import { innerScope, visibleVariables } from "./step-input.js";
+import { runTask } from "./task.js";
+//#region src/run/result-states.ts
+const task = async (state, call) => {
+	const args = await evaluateTemplate(state.Arguments ?? {}, call.bindings, "Arguments");
+	const key = `${call.context.runId}/${call.scope}/${call.position.seq - call.position.attempt + 1}`;
+	const input = redacted(recordedArguments(state.Arguments ?? {}, args));
+	return runTask(call.context, state, args, key, call.logs).then((result) => ({
+		result,
+		input
+	}), (error) => {
+		if (!(error instanceof StepError)) throw error;
+		return {
+			failure: errorOutput(error),
+			input
+		};
+	});
+};
+const map = async (state, call) => {
+	const items = await evaluateKept(state.Items, call.bindings, "Items");
+	if (!Array.isArray(items)) throw new StepError("States.QueryEvaluationError", `Items: gave ${JSON.stringify(items) ?? "nothing"}, not an array`);
+	if (items.length > limits.mapItems) throw new StepError("States.DataLimitExceeded", `Items: ${items.length} items, more than the ${limits.mapItems} a Map takes`);
+	const outer = visibleVariables(call.bindings);
+	let kept = 0;
+	const scopes = items.map((item, index) => async () => {
+		const outcome = await call.runScope(state.ItemProcessor, innerScope(call.scope, call.name, call.position.seq, index), item, outer);
+		if (outcome.kind !== "ended") return outcome;
+		kept += jsonBytes(outcome.output);
+		if (kept <= limits.valueBytes) return outcome;
+		return {
+			kind: "failed",
+			error: "States.DataLimitExceeded",
+			cause: `The items' outputs are larger than ${limits.valueBytes / 1024 / 1024} MiB together`
+		};
+	});
+	const outcome = await fanOut(scopes, state.MaxConcurrency || limits.mapConcurrency);
+	if (outcome.kind === "blocked" || outcome.kind === "yielded") return outcome;
+	const input = { items: items.length };
+	if (outcome.kind === "failed") return {
+		failure: {
+			Error: outcome.error,
+			Cause: outcome.cause
+		},
+		input
+	};
+	call.logs.push({
+		at: call.context.now().toISOString(),
+		message: `${items.length} items`
+	});
+	return {
+		result: outcome.outputs,
+		input
+	};
+};
+const attempt = async (state, call) => {
+	try {
+		if (state.Type === "Task") return await task(state, call);
+		return await map(state, call);
+	} catch (error) {
+		if (!(error instanceof StepError)) throw error;
+		return {
+			failure: errorOutput(error),
+			input: void 0
+		};
+	}
+};
+/**
+* A Task or a Map: its result shaped by `Output` and `Assign`, which read it as `$states.result`; a failure,
+* its own or an item's, goes to its retriers and catchers.
+*/
+const runResultState = async (state, call) => {
+	const ran = await attempt(state, call);
+	if ("kind" in ran) return ran;
+	const now = call.context.now();
+	if ("failure" in ran) return {
+		...await recover(state, call.position, ran.failure, call.bindings, now, call.logs),
+		...ran.input !== void 0 && { input: ran.input }
+	};
+	const after = {
+		...call.bindings,
+		states: {
+			...call.bindings.states,
+			result: ran.result
+		}
+	};
+	const shaped = async () => ({
+		output: state.Output === void 0 ? ran.result : await evaluateKept(state.Output, after, "Output"),
+		assigned: await evaluateAssign(state.Assign, after)
+	});
+	const done = await shaped().catch((error) => {
+		if (!(error instanceof StepError)) throw error;
+		return { failure: errorOutput(error) };
+	});
+	if ("failure" in done) return {
+		...await recover(state, call.position, done.failure, call.bindings, now, call.logs),
+		input: ran.input
+	};
+	return {
+		kind: "step",
+		status: "succeeded",
+		next: state.Next ?? null,
+		input: ran.input,
+		...done,
+		logs: call.logs
+	};
+};
+//#endregion
+export { runResultState };

package/dist/run/runner.d.ts

@@ -0,0 +1,29 @@
+import { RunStore, SegmentQueue, TaskHandlers } from "./port.js";
+//#region src/run/runner.d.ts
+/**
+ * The runner's port: where runs are kept, the queue that runs their segments, the step types, and the secrets
+ * expressions may read by name, which the runner blanks out of all a run records.
+ */
+export type RunnerPort<Db> = {
+  store: RunStore<Db>;
+  queue: SegmentQueue<Db>;
+  tasks: TaskHandlers;
+  secrets?: Readonly<Record<string, string>>;
+  now?: () => Date;
+  budgetMs?: number;
+  maxSteps?: number;
+};
+/**
+ * The workflow runner over a port. `start` queues a run's first segment in `db`, which may be the caller's
+ * transaction, so the run starts when it commits; `segment` is what the queue's job runs.
+ */
+export declare const createRunner: <Db>({ store, queue, tasks, secrets, now, budgetMs, maxSteps }: RunnerPort<Db>) => {
+  start: (db: Db, runId: string) => Promise<void>;
+  /**
+   * Runs the run from where it stands to its next wait, then queues the next segment or ends the run. Run again after
+   * a crash, it takes up from the last saved step: only the step that was in progress runs again.
+   */
+  segment: (db: Db, runId: string, signal: AbortSignal) => Promise<void>;
+};
+export type Runner<Db> = ReturnType<typeof createRunner<Db>>;
+//#endregion

package/dist/run/runner.js

@@ -0,0 +1,60 @@
+import { limits } from "../limits.js";
+import { secretRedactor } from "./redact.js";
+import { runSegment } from "./segment.js";
+//#region src/run/runner.ts
+const ended = /* @__PURE__ */ new Set(["succeeded", "failed"]);
+/**
+* The workflow runner over a port. `start` queues a run's first segment in `db`, which may be the caller's
+* transaction, so the run starts when it commits; `segment` is what the queue's job runs.
+*/
+const createRunner = ({ store, queue, tasks, secrets = {}, now = () => /* @__PURE__ */ new Date(), budgetMs = limits.segmentMs, maxSteps = limits.runSteps }) => {
+	const redactor = secretRedactor(Object.values(secrets));
+	return {
+		start: (db, runId) => queue.schedule(db, runId),
+		/**
+		* Runs the run from where it stands to its next wait, then queues the next segment or ends the run. Run again after
+		* a crash, it takes up from the last saved step: only the step that was in progress runs again.
+		*/
+		segment: async (db, runId, signal) => {
+			const run = await store.load(db, runId);
+			if (!run || ended.has(run.status)) return;
+			await store.update(db, runId, { status: "running" });
+			const segment = {
+				runId,
+				definition: run.definition,
+				input: run.input,
+				startedAt: run.startedAt,
+				secrets,
+				redactor,
+				tasks,
+				signal,
+				now,
+				budgetMs,
+				maxSteps
+			};
+			const outcome = await runSegment({
+				...segment,
+				saved: await store.steps(db, runId),
+				save: (steps) => store.save(db, runId, steps)
+			});
+			if (outcome.kind === "superseded") return;
+			if (outcome.kind === "ended") return store.update(db, runId, {
+				status: "succeeded",
+				output: redactor.value(outcome.output)
+			});
+			if (outcome.kind === "failed") return store.update(db, runId, {
+				status: "failed",
+				error: redactor.text(outcome.error),
+				cause: redactor.text(outcome.cause)
+			});
+			if (outcome.kind === "yielded") return queue.schedule(db, runId);
+			await store.update(db, runId, {
+				status: "waiting",
+				resumeAt: outcome.until
+			});
+			await queue.schedule(db, runId, outcome.until);
+		}
+	};
+};
+//#endregion
+export { createRunner };

package/dist/run/scope.js

@@ -0,0 +1,127 @@
+import { limits } from "../limits.js";
+import { StepError, SupersededError } from "./errors.js";
+import { jsonBytes } from "./json-bytes.js";
+import { advance, foldPosition } from "./position.js";
+import { bindingsOf } from "./step-input.js";
+import { runResultState } from "./result-states.js";
+import { runChoice, runFail, runPass, runWait } from "./simple-states.js";
+//#region src/run/scope.ts
+const runState = (state, call) => {
+	if (state.Type === "Pass" || state.Type === "Succeed") return runPass(state, call);
+	if (state.Type === "Choice") return runChoice(state, call);
+	if (state.Type === "Wait") return runWait(state, call);
+	if (state.Type === "Fail") return runFail(state, call);
+	return runResultState(state, call);
+};
+const ranOrFailed = async (state, call) => {
+	try {
+		return await runState(state, call);
+	} catch (error) {
+		if (!(error instanceof StepError)) throw error;
+		return {
+			kind: "step",
+			status: "failed",
+			next: null,
+			input: call.position.input,
+			error: error.error,
+			cause: error.reason,
+			logs: call.logs
+		};
+	}
+};
+const keptLogs = (logs, redact) => {
+	const cut = (message) => {
+		const text = redact(message);
+		return text.length > limits.logLineLength ? `${text.slice(0, limits.logLineLength)}…` : text;
+	};
+	const kept = logs.slice(0, limits.logLines).map((line) => ({
+		...line,
+		message: cut(line.message)
+	}));
+	if (logs.length <= limits.logLines) return kept;
+	return [...kept, {
+		at: logs.at(-1).at,
+		message: `… ${logs.length - limits.logLines} more lines not kept`
+	}];
+};
+const withinLimits = (record) => {
+	const field = [
+		"input",
+		"output",
+		"assigned"
+	].find((name) => jsonBytes(record[name]) > limits.valueBytes);
+	if (!field) return record;
+	const { output: _, assigned: __, input: ___, ...rest } = record;
+	return {
+		...rest,
+		status: "failed",
+		next: null,
+		resumeAt: null,
+		error: "States.DataLimitExceeded",
+		cause: `The step's ${field} is larger than ${limits.valueBytes / 1024 / 1024} MiB`
+	};
+};
+/**
+* Runs one scope (the run or a Map item) from where its saved steps leave it, saving each step as
+* the segment's checkpoints come, until the scope ends or fails, waits for a time, or the segment's time is up.
+*/
+const runScope = async (context, machine, scope, input, outer) => {
+	let position = foldPosition(machine, input, context.saved.get(scope) ?? []);
+	for (;;) {
+		if (position.kind === "ended") return {
+			kind: "ended",
+			output: position.output
+		};
+		if (position.kind === "failed") return {
+			kind: "failed",
+			error: position.error,
+			cause: position.cause
+		};
+		if (context.superseded()) throw new SupersededError(`Scope "${scope}" stopped: another segment saved a step of this run first`);
+		if (position.resumeAt && position.resumeAt > context.now()) return {
+			kind: "blocked",
+			until: position.resumeAt
+		};
+		if (Date.now() >= context.deadline) return { kind: "yielded" };
+		if (context.steps.count >= context.maxSteps) return {
+			kind: "failed",
+			error: "States.Runtime",
+			cause: `The run took more than ${context.maxSteps} steps`
+		};
+		const name = position.state;
+		const state = machine.States[name];
+		const startedAt = context.now();
+		const call = {
+			context,
+			name,
+			scope,
+			position,
+			bindings: bindingsOf(context, outer, position),
+			logs: [],
+			runScope: (inner, key, value, seen) => runScope(context, inner, key, value, seen)
+		};
+		context.steps.count++;
+		const result = await ranOrFailed(state, call);
+		if (result.kind !== "step") {
+			context.steps.count--;
+			return result;
+		}
+		const { kind: _, logs, ...step } = result;
+		const shaped = {
+			...step,
+			logs: keptLogs(logs, context.redactor.text),
+			scope,
+			seq: position.seq,
+			state: name,
+			type: state.Type,
+			attempt: position.attempt,
+			startedAt,
+			finishedAt: context.now()
+		};
+		const record = withinLimits(context.redactor.value(shaped));
+		await context.save(record, state.Type === "Task" || Boolean(record.resumeAt));
+		position = advance(position, record);
+	}
+};
+//#endregion
+export { runScope };

package/dist/run/segment.d.ts

@@ -0,0 +1,35 @@
+import { Definition } from "../definition/types.js";
+import { Redactor } from "./redact.js";
+import { SavedStep, StepRecord, TaskHandlers } from "./port.js";
+import { ScopeOutcome } from "./context.js";
+//#region src/run/segment.d.ts
+export type SegmentInput = {
+  runId: string;
+  definition: Definition;
+  input: unknown;
+  /** When the run started, which expressions read as `$states.context.Execution.StartTime`. */
+  startedAt: Date;
+  /** The secrets expressions may read as `$states.context.Secrets.<NAME>`, by name. */
+  secrets: Readonly<Record<string, string>>;
+  /** Blanks the secrets out of what the run records. */
+  redactor: Redactor;
+  /** The steps the run saved so far. */
+  saved: readonly SavedStep[];
+  /** Saves steps in one guarded statement: false when any of their scopes and seqs is taken. */
+  save: (steps: readonly StepRecord[]) => Promise<boolean>;
+  tasks: TaskHandlers;
+  signal: AbortSignal;
+  now?: () => Date;
+  /** How long the segment takes new steps. Default `limits.segmentMs`. */
+  budgetMs?: number;
+  /** The most steps the run takes. Default `limits.runSteps`. */
+  maxSteps?: number;
+};
+/**
+ * Runs a run's steps from where its saved steps leave it to its next wait: it ends or fails, waits until a time
+ * (a Wait, a retry's delay), or yields once its time is up. `superseded` when another segment saved a step first.
+ */
+export declare const runSegment: ({ runId, definition, input, startedAt, secrets, redactor, saved, save, tasks, signal, now, budgetMs, maxSteps }: SegmentInput) => Promise<ScopeOutcome | {
+  kind: "superseded";
+}>;
+//#endregion

package/dist/run/segment.js

@@ -0,0 +1,58 @@
+import { limits } from "../limits.js";
+import { SupersededError } from "./errors.js";
+import { runScope } from "./scope.js";
+//#region src/run/segment.ts
+/**
+* Runs a run's steps from where its saved steps leave it to its next wait: it ends or fails, waits until a time
+* (a Wait, a retry's delay), or yields once its time is up. `superseded` when another segment saved a step first.
+*/
+const runSegment = async ({ runId, definition, input, startedAt, secrets, redactor, saved, save, tasks, signal, now = () => /* @__PURE__ */ new Date(), budgetMs = limits.segmentMs, maxSteps = limits.runSteps }) => {
+	const byScope = /* @__PURE__ */ new Map();
+	for (const step of [...saved].sort((a, b) => a.seq - b.seq)) {
+		const steps = byScope.get(step.scope);
+		if (steps) steps.push(step);
+		else byScope.set(step.scope, [step]);
+	}
+	let superseded = false;
+	let kept = [];
+	const write = async () => {
+		const steps = kept;
+		kept = [];
+		if (steps.length === 0 || await save(steps)) return;
+		superseded = true;
+		throw new SupersededError(`Step ${steps[0].seq} of scope "${steps[0].scope}" was saved by another segment`);
+	};
+	const context = {
+		runId,
+		stateContext: {
+			Execution: {
+				Input: input,
+				StartTime: startedAt.toISOString()
+			},
+			Secrets: secrets
+		},
+		redactor,
+		tasks,
+		signal,
+		now,
+		deadline: Date.now() + budgetMs,
+		saved: byScope,
+		save: async (step, checkpoint) => {
+			kept.push(step);
+			if (checkpoint) await write();
+		},
+		superseded: () => superseded,
+		steps: { count: saved.length },
+		maxSteps
+	};
+	try {
+		const outcome = await runScope(context, definition.stateMachine, "", input, {});
+		await write();
+		return outcome;
+	} catch (error) {
+		if (!(error instanceof SupersededError)) throw error;
+		return { kind: "superseded" };
+	}
+};
+//#endregion
+export { runSegment };

package/dist/run/simple-states.js

@@ -0,0 +1,108 @@
+import { limits } from "../limits.js";
+import { StepError } from "./errors.js";
+import { evaluateAssign, evaluateKept, evaluateTemplate } from "./evaluate.js";
+//#region src/run/simple-states.ts
+const nextOf = (state) => state.Next ?? null;
+const outputOf = async (state, call) => state.Output === void 0 ? call.position.input : evaluateKept(state.Output, call.bindings, "Output");
+const runPass = async (state, call) => ({
+	kind: "step",
+	status: "succeeded",
+	next: state.Type === "Pass" ? nextOf(state) : null,
+	input: call.position.input,
+	output: await outputOf(state, call),
+	assigned: await evaluateAssign("Assign" in state ? state.Assign : void 0, call.bindings),
+	logs: call.logs
+});
+const runChoice = async (state, call) => {
+	for (const [index, rule] of state.Choices.entries()) {
+		const field = `Choices[${index}].Condition`;
+		const holds = await evaluateTemplate(rule.Condition, call.bindings, field);
+		if (typeof holds !== "boolean") throw new StepError("States.QueryEvaluationError", `${field}: gave ${JSON.stringify(holds) ?? "nothing"}, not true or false`);
+		if (!holds) continue;
+		call.logs.push({
+			at: call.context.now().toISOString(),
+			message: `Choice ${index + 1} holds`
+		});
+		const shaped = {
+			Output: rule.Output === void 0 ? state.Output : rule.Output,
+			Assign: rule.Assign ?? state.Assign
+		};
+		return {
+			kind: "step",
+			status: "succeeded",
+			next: rule.Next,
+			input: call.position.input,
+			output: await outputOf(shaped, call),
+			assigned: await evaluateAssign(shaped.Assign, call.bindings),
+			logs: call.logs
+		};
+	}
+	if (state.Default === void 0) throw new StepError("States.NoChoiceMatched", "No choice holds and the state has no Default");
+	call.logs.push({
+		at: call.context.now().toISOString(),
+		message: "No choice holds: Default"
+	});
+	return {
+		kind: "step",
+		status: "succeeded",
+		next: state.Default,
+		input: call.position.input,
+		output: await outputOf(state, call),
+		assigned: await evaluateAssign(state.Assign, call.bindings),
+		logs: call.logs
+	};
+};
+const isoPattern = /^(\d{4})-(\d{2})-(\d{2})T([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$/;
+const isoTime = (text) => {
+	const match = isoPattern.exec(text);
+	if (!match) return void 0;
+	const [year, month, day] = [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+	const date = new Date(Date.UTC(year, month - 1, day));
+	if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return void 0;
+	return new Date(text);
+};
+const waitUntil = async (state, call) => {
+	const now = call.context.now();
+	if (state.Seconds !== void 0) {
+		const seconds = await evaluateTemplate(state.Seconds, call.bindings, "Seconds");
+		if (typeof seconds !== "number" || !(seconds >= 0) || seconds > limits.waitSeconds) throw new StepError("States.QueryEvaluationError", `Seconds: gave ${JSON.stringify(seconds) ?? "nothing"}, not a number of seconds from 0 to ${limits.waitSeconds}`);
+		return new Date(now.getTime() + seconds * 1e3);
+	}
+	const timestamp = await evaluateTemplate(state.Timestamp, call.bindings, "Timestamp");
+	const at = typeof timestamp === "string" ? isoTime(timestamp) : void 0;
+	if (!at) throw new StepError("States.QueryEvaluationError", `Timestamp: gave ${JSON.stringify(timestamp) ?? "nothing"}, not an ISO 8601 time such as 2026-11-04T12:00:00Z`);
+	if (at.getTime() - now.getTime() > limits.waitSeconds * 1e3) throw new StepError("States.QueryEvaluationError", `Timestamp: gave ${JSON.stringify(timestamp)}, more than ${limits.waitSeconds} seconds from now`);
+	return at;
+};
+/** A Wait saves its step at once, with the time the next state may run: the segment ends there, and the queue wakes the run. */
+const runWait = async (state, call) => {
+	const resumeAt = await waitUntil(state, call);
+	return {
+		kind: "step",
+		status: "succeeded",
+		next: nextOf(state),
+		input: call.position.input,
+		output: await outputOf(state, call),
+		assigned: await evaluateAssign(state.Assign, call.bindings),
+		resumeAt,
+		logs: call.logs
+	};
+};
+const runFail = async (state, call) => {
+	const text = async (value, field) => value === void 0 ? void 0 : String(await evaluateKept(value, call.bindings, field));
+	return {
+		kind: "step",
+		status: "failed",
+		next: null,
+		input: call.position.input,
+		error: await text(state.Error, "Error") ?? "States.Fail",
+		cause: await text(state.Cause, "Cause") ?? "",
+		logs: call.logs
+	};
+};
+//#endregion
+export { runChoice, runFail, runPass, runWait };

package/dist/run/step-input.js

@@ -0,0 +1,22 @@
+//#region src/run/step-input.ts
+/**
+* The names an expression reads in a scope: the outer scopes' variables, this one's, and `$states` with the run's
+* context and the state's input as `$states.input`, which the check lets only a Map item's first state read.
+*/
+const bindingsOf = (context, outer, position) => ({
+	...outer,
+	...position.variables,
+	states: {
+		input: position.input,
+		context: context.stateContext
+	}
+});
+/** The variables an inner scope sees: every one in scope here, without `$states`, which each scope adds itself. */
+const visibleVariables = ({ states: _, ...variables }) => variables;
+/**
+* The key of an inner scope: item `index` of the Map `name` that was step `seq` of `scope`, such as `Each.3[0]`. The
+* name is URI-encoded, so a `/` or `[` in a state's name cannot make two scopes' keys the same.
+*/
+const innerScope = (scope, name, seq, index) => `${scope ? `${scope}/` : ""}${encodeURIComponent(name)}.${seq}[${index}]`;
+//#endregion
+export { bindingsOf, innerScope, visibleVariables };