bazis 0.132.0 → 0.134.0

package/library/workflow/cron.ts

@@ -1,4 +1,4 @@
-/** A parsed five-field cron expression, evaluated in UTC. */
+/** A parsed five-field cron expression, evaluated in UTC or in a time zone. */
 export interface CronSchedule {
   /** Whether the expression fires at this minute. */
   matches(date: Date): boolean;
@@ -15,14 +15,53 @@ const FIELDS = [
 ] as const;
 
 const MINUTE = 60_000;
+const DAY_MINUTES = 24 * 60;
+/** Clock changes are never longer than this: a day is skipped up to here, the rest hour by hour. */
+const CLOCK_CHANGE_MINUTES = 3 * 60;
+
+const formats = new Map<string, Intl.DateTimeFormat>();
+
+function formatOf(timezone: string): Intl.DateTimeFormat {
+  let format = formats.get(timezone);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat("en-US", { timeZone: timezone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+    formats.set(timezone, format);
+  }
+  return format;
+}
+
+/** Whether this is an IANA time zone: `Europe/Moscow`, `UTC`. */
+export function isTimeZone(value: unknown): value is string {
+  if (typeof value !== "string" || value === "") return false;
+  try {
+    formatOf(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** How far the clocks of the zone are ahead of UTC at this moment, in milliseconds. */
+function offsetOf(timezone: string | undefined, time: number): number {
+  if (timezone === undefined) return 0;
+  const parts: Record<string, number> = {};
+  for (const { type, value } of formatOf(timezone).formatToParts(time)) parts[type] = Number(value);
+  return Date.UTC(parts.year!, parts.month! - 1, parts.day!, parts.hour!, parts.minute!, parts.second!) - Math.floor(time / 1000) * 1000;
+}
 
 /**
  * Parses `minute hour day-of-month month day-of-week` with `*`, numbers,
  * ranges `a-b`, steps `/n` and lists `a,b`. Day of week 0 and 7 are Sunday.
  * When both day fields are restricted, either one matching is enough, as in
- * classic cron. Returns `undefined` for an invalid expression.
+ * classic cron. Returns `undefined` for an invalid expression or time zone.
+ *
+ * With a `timezone` the fields are read on its clocks. A schedule with a set
+ * hour fires once a day whatever the clocks do: a time skipped when they go
+ * forward fires right after the change, a time repeated when they go back fires
+ * the first time only. A schedule with `*` in the hour simply follows the clocks.
  */
-export function parseCron(expression: string): CronSchedule | undefined {
+export function parseCron(expression: string, timezone?: string): CronSchedule | undefined {
+  if (timezone !== undefined && !isTimeZone(timezone)) return undefined;
   const parts = expression.trim().split(/\s+/);
   if (parts.length !== 5) return undefined;
   const sets: Set<number>[] = [];
@@ -35,34 +74,74 @@ export function parseCron(expression: string): CronSchedule | undefined {
   if (weekdays.has(7)) weekdays.add(0);
   const daysRestricted = parts[2] !== "*";
   const weekdaysRestricted = parts[4] !== "*";
+  const hourSet = parts[1] !== "*";
 
-  const dayMatches = (date: Date): boolean => {
-    const day = days.has(date.getUTCDate());
-    const weekday = weekdays.has(date.getUTCDay());
-    return daysRestricted && weekdaysRestricted ? day || weekday : day && weekday;
+  /** The date part of a time on the clocks of the zone, kept in the UTC fields of a `Date`. */
+  const dayMatches = (clock: Date): boolean => {
+    const day = days.has(clock.getUTCDate());
+    const weekday = weekdays.has(clock.getUTCDay());
+    return months.has(clock.getUTCMonth() + 1) && (daysRestricted && weekdaysRestricted ? day || weekday : day && weekday);
   };
 
-  const matches = (date: Date): boolean =>
-    minutes.has(date.getUTCMinutes()) && hours.has(date.getUTCHours()) && months.has(date.getUTCMonth() + 1) && dayMatches(date);
+  const clockMatches = (clock: Date): boolean => minutes.has(clock.getUTCMinutes()) && hours.has(clock.getUTCHours()) && dayMatches(clock);
+
+  /** Whether the clocks show this time for the second time: they went back a moment ago. */
+  const repeated = (time: number, offset: number): boolean => {
+    const before = offsetOf(timezone, time - CLOCK_CHANGE_MINUTES * MINUTE);
+    if (before <= offset) return false;
+    const first = time - (before - offset);
+    return offsetOf(timezone, first) === before;
+  };
+
+  /** When the clocks jumped forward between two moments, if a firing fell into the skipped time. */
+  const skippedFiring = (from: number, to: number): number | undefined => {
+    const before = offsetOf(timezone, from);
+    const after = offsetOf(timezone, to);
+    if (after <= before) return undefined;
+    let low = from;
+    let high = to;
+    while (high - low > MINUTE) {
+      const middle = Math.floor((low + high) / 2 / MINUTE) * MINUTE;
+      if (offsetOf(timezone, middle) === before) low = middle;
+      else high = middle;
+    }
+    for (let clock = high + before; clock < high + after; clock += MINUTE) {
+      if (clockMatches(new Date(clock))) return high;
+    }
+    return undefined;
+  };
 
   return {
-    matches,
+    matches(date: Date): boolean {
+      const offset = offsetOf(timezone, date.getTime());
+      if (!clockMatches(new Date(date.getTime() + offset))) return false;
+      return !(hourSet && timezone !== undefined && repeated(Math.floor(date.getTime() / MINUTE) * MINUTE, offset));
+    },
     next(after: Date): Date | undefined {
-      const limit = after.getTime() + 5 * 366 * 24 * 60 * MINUTE;
-      const date = new Date(Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE);
-      while (date.getTime() <= limit) {
-        if (!months.has(date.getUTCMonth() + 1)) {
-          date.setUTCMonth(date.getUTCMonth() + 1, 1);
-          date.setUTCHours(0, 0, 0, 0);
-        } else if (!dayMatches(date)) {
-          date.setUTCDate(date.getUTCDate() + 1);
-          date.setUTCHours(0, 0, 0, 0);
-        } else if (!hours.has(date.getUTCHours())) {
-          date.setUTCHours(date.getUTCHours() + 1, 0, 0, 0);
-        } else if (!minutes.has(date.getUTCMinutes())) {
-          date.setTime(date.getTime() + MINUTE);
+      const limit = after.getTime() + 5 * 366 * DAY_MINUTES * MINUTE;
+      let time = Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE;
+      let previous = time - MINUTE;
+      while (time <= limit) {
+        if (hourSet && timezone !== undefined) {
+          const skipped = skippedFiring(previous, time);
+          if (skipped !== undefined) return new Date(skipped);
+        }
+        previous = time;
+        const offset = offsetOf(timezone, time);
+        const clock = new Date(time + offset);
+        const minutesOfDay = clock.getUTCHours() * 60 + clock.getUTCMinutes();
+        if (!dayMatches(clock)) {
+          // Close to midnight hour by hour: the day may be shorter than its clocks say.
+          const left = DAY_MINUTES - minutesOfDay;
+          time += (timezone === undefined ? left : left > CLOCK_CHANGE_MINUTES ? left - CLOCK_CHANGE_MINUTES : 60 - clock.getUTCMinutes()) * MINUTE;
+        } else if (!hours.has(clock.getUTCHours())) {
+          time += (60 - clock.getUTCMinutes()) * MINUTE;
+        } else if (!minutes.has(clock.getUTCMinutes())) {
+          time += MINUTE;
+        } else if (hourSet && timezone !== undefined && repeated(time, offset)) {
+          time += MINUTE;
         } else {
-          return date;
+          return new Date(time);
         }
       }
       return undefined;

package/library/workflow/expressions.ts

@@ -265,6 +265,8 @@ export interface ExpressionScope {
   readonly vars?: ReadonlySet<string>;
   /** Nodes: `$nodes.<node>`. */
   readonly nodes?: ReadonlySet<string>;
+  /** Whether it is read inside a loop body: `$item` and `$index` exist only there. */
+  readonly loop?: boolean;
 }
 
 /** What is wrong with an expression, or `null`: its shape, functions, argument types, paths and limits. */
@@ -331,9 +333,11 @@ function literalArgumentProblem(name: ExprFunctionName, args: readonly unknown[]
 
 /** What is wrong with a `$` path, or `null`. */
 export function checkPath(path: unknown, scope: ExpressionScope = {}): string | null {
-  if (typeof path !== "string" || !DATA_PATH.test(path)) return `path ${JSON.stringify(path)} must look like $input.field, $vars.name, $nodes.Node.field, $event.field, $trigger, $run.id or $now`;
+  if (typeof path !== "string" || !DATA_PATH.test(path)) return `path ${JSON.stringify(path)} must look like $input.field, $vars.name, $nodes.Node.field, $event.field, $trigger, $run.id, $now, $item.field or $index`;
   const [root, first] = path.split(".");
   if (root === "$now" && first !== undefined) return "$now has no fields";
+  if (root === "$index" && first !== undefined) return "$index has no fields";
+  if ((root === "$item" || root === "$index") && scope.loop === false) return `path ${path}: ${root} exists only inside a loop body`;
   if (root === "$nodes" && first === undefined) return "$nodes needs a node: $nodes.Node.field";
   if (first === undefined) return null;
   if (root === "$input" && scope.input && !scope.input.has(first)) return `path ${path}: the input has no field ${first}`;

package/library/workflow/index.ts

@@ -20,7 +20,7 @@ export {
   type ProcessNode,
   type ProcessSettings,
 } from "./ProcessDocument";
-export { NODE_KINDS, nodeKindOf, ISO_DURATION, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
+export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, ISO_MOMENT, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
 export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, type InstanceData } from "./paths";
 export {
@@ -42,7 +42,7 @@ export {
 } from "./expressions";
 export { ExpressionSyntaxError, parseExpression, printExpression } from "./expressionSyntax";
 export { durationMs } from "./duration";
-export { parseCron, type CronSchedule } from "./cron";
+export { isTimeZone, parseCron, type CronSchedule } from "./cron";
 export { processToMermaid } from "./mermaid";
 export { PERSONAL_MASK, maskByMapping, maskBySchema, masksPersonal, personalPaths, personalVariables, readsPersonal } from "./masking";
 export { allTexts, checkLocalizedText, textOf, type LocalizedText } from "./localized";

package/library/workflow/masking.ts

@@ -14,9 +14,23 @@ export function masksPersonal(document: Pick<ProcessDocument, "settings">): bool
   return document.settings?.log?.maskPersonal !== false;
 }
 
-/** The paths of the personal variables: `$input.email`, `$vars.email`. */
-export function personalPaths(document: Pick<ProcessDocument, "variables">): ReadonlySet<string> {
-  return new Set((document.variables ?? []).filter((variable) => variable.personal === true).map((variable) => `${variable.direction === "in" ? "$input" : "$vars"}.${variable.name}`));
+/**
+ * The paths of the personal variables: `$input.email`, `$vars.email`. A loop over
+ * personal data adds its element: `$item` and the name the loop gives it.
+ */
+export function personalPaths(document: Pick<ProcessDocument, "variables"> & Partial<Pick<ProcessDocument, "nodes">>): ReadonlySet<string> {
+  const paths = new Set((document.variables ?? []).filter((variable) => variable.personal === true).map((variable) => `${variable.direction === "in" ? "$input" : "$vars"}.${variable.name}`));
+  const loops = Object.values(document.nodes ?? {}).filter((node) => node.kind === "loop" && node.config?.over !== undefined);
+  // A loop over the element of another loop: as many passes as it takes.
+  for (let size = -1; size !== paths.size;) {
+    size = paths.size;
+    for (const { config } of loops) {
+      if (!readsPersonal(config!.over, paths)) continue;
+      paths.add("$item");
+      if (typeof config!.item === "string") paths.add(`$vars.${config!.item}`);
+    }
+  }
+  return paths;
 }
 
 /** The names of the personal `local` and `out` variables. */

package/library/workflow/mermaid.ts

@@ -13,6 +13,8 @@ const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
   end: ["((", "))"],
   userTask: ["[", "]"],
   serviceTask: ["[[", "]]"],
+  callProcess: ["[[", "]]"],
+  loop: ["[", "]"],
   assign: ["[/", "/]"],
   timerCatch: ["{{", "}}"],
   eventWait: ["{{", "}}"],
@@ -25,7 +27,7 @@ const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
 
 /**
  * A process as a Mermaid `flowchart` (WORKFLOW-001 §14): starts are stadiums,
- * Tool steps subroutines, tasks rectangles, waits hexagons, gateways rhombi,
+ * Tool steps and called processes subroutines, a loop a subgraph around its body, tasks rectangles, waits hexagons, gateways rhombi,
  * ends and boundary events circles. A boundary event hangs on its step by a
  * dotted link. Labels show the node kind's detail: the Tool, the cron, the
  * duration, the event key; flows show their title or condition.
@@ -43,11 +45,23 @@ export function processToMermaid(document: ProcessDocument, direction: "LR" | "T
     return id;
   };
   const lines = [`flowchart ${direction}`];
-  for (const [nodeId, node] of Object.entries(document.nodes)) {
-    const [open, close] = SHAPES[node.kind] ?? ["[", "]"];
-    const detail = detailOf(node.kind, node.config ?? {});
-    lines.push(`  ${idOf(nodeId)}${open}"${label(textOf(node.title, "en") || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}"${close}`);
-  }
+  // A loop is a subgraph around its body; flows and boundaries link to it by its id.
+  const write = (parent: string | undefined, indent: string): void => {
+    for (const [nodeId, node] of Object.entries(document.nodes)) {
+      if (node.parent !== parent) continue;
+      const detail = detailOf(node.kind, node.config ?? {});
+      const text = `${label(textOf(node.title, "en") || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}`;
+      if (node.kind === "loop") {
+        lines.push(`${indent}subgraph ${idOf(nodeId)}["${text}"]`);
+        write(nodeId, `${indent}  `);
+        lines.push(`${indent}end`);
+        continue;
+      }
+      const [open, close] = SHAPES[node.kind] ?? ["[", "]"];
+      lines.push(`${indent}${idOf(nodeId)}${open}"${text}"${close}`);
+    }
+  };
+  write(undefined, "  ");
   for (const [nodeId, node] of Object.entries(document.nodes)) {
     if (node.attachedTo !== undefined && document.nodes[node.attachedTo] !== undefined) lines.push(`  ${idOf(node.attachedTo)} -.- ${idOf(nodeId)}`);
   }
@@ -63,6 +77,8 @@ function detailOf(kind: NodeKind, config: Readonly<Record<string, unknown>>): st
   const text = (value: unknown) => (typeof value === "string" && value !== "" ? value : undefined);
   switch (kind) {
     case "serviceTask": return text(config.tool);
+    case "callProcess": return text(config.process);
+    case "loop": return typeof config.times === "number" ? `${config.times} times` : config.while !== undefined ? "while" : "for each";
     case "scheduleStart": return text(config.cron);
     case "eventStart":
     case "eventWait":

package/library/workflow/nodeKinds.ts

@@ -1,4 +1,4 @@
-import { parseCron } from "./cron";
+import { isTimeZone, parseCron } from "./cron";
 import { FIELD_NAME, checkFormSpec } from "./formFields";
 import { DATA_PATH } from "./paths";
 import type { NodeKind } from "./ProcessDocument";
@@ -12,6 +12,8 @@ export type JsonSchema = Readonly<Record<string, unknown>>;
 export interface NodeKindDefinition {
   readonly kind: NodeKind;
   readonly role: NodeRole;
+  /** A container: other nodes name it as their `parent`. */
+  readonly container?: boolean;
   /** Checks the node `config`; returns a problem or `null`. */
   readonly check: (config: Record<string, unknown>) => string | null;
   /** The node `config` as a JSON Schema: what a designer builds the form of a step from. */
@@ -22,6 +24,12 @@ export interface NodeKindDefinition {
 export const ISO_DURATION = /^P(?!$)(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
 /** An event key or a Tool name: `payments.received`, `payments.charge`. */
 export const DOTTED_KEY = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$/;
+/** A process key. */
+export const PROCESS_KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+/** The most iterations a loop may have. */
+export const MAX_ITERATIONS = 10_000;
+/** The most iterations of a loop that run at once. */
+export const MAX_LOOP_PARALLEL = 100;
 /** A parameter of a Tool. */
 const PARAMETER = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 const ROLE = /^[a-z][a-z0-9_.-]{0,63}$/;
@@ -44,11 +52,42 @@ function first(...checks: (string | null)[]): string | null {
   return checks.find((check) => check !== null) ?? null;
 }
 
-/** Five cron fields: minute, hour, day of month, month, day of week. */
-function cron(config: Record<string, unknown>): string | null {
-  const value = config.cron;
-  if (typeof value !== "string") return "config.cron is required";
-  return parseCron(value) === undefined ? "config.cron must be five valid fields: minute hour day month weekday (UTC)" : null;
+/** A moment with its zone: `2026-11-01T09:00:00+03:00`. */
+export const ISO_MOMENT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+
+function moment(config: Record<string, unknown>, key: string): string | null {
+  const value = config[key];
+  if (value === undefined) return null;
+  return typeof value === "string" && ISO_MOMENT.test(value) && !Number.isNaN(Date.parse(value)) ? null : `config.${key} must be a moment with its zone: 2026-11-01T09:00:00+03:00`;
+}
+
+/** A scheduled start: five cron fields (minute, hour, day of month, month, day of week), where and when it runs. */
+function schedule(config: Record<string, unknown>): string | null {
+  const { cron, timezone, from, until, overlap, partitions } = config;
+  if (typeof cron !== "string") return "config.cron is required";
+  if (parseCron(cron) === undefined) return "config.cron must be five valid fields: minute hour day month weekday";
+  if (timezone !== undefined && !isTimeZone(timezone)) return "config.timezone must be an IANA time zone: Europe/Moscow";
+  const period = first(moment(config, "from"), moment(config, "until"), boolean(config, "catchUp"));
+  if (period !== null) return period;
+  if (typeof from === "string" && typeof until === "string" && Date.parse(from) >= Date.parse(until)) return "config.from must be before config.until";
+  if (overlap !== undefined && overlap !== "skip" && overlap !== "queue" && overlap !== "parallel") return "config.overlap must be skip, queue or parallel";
+  if (partitions !== undefined && partitions !== "none" && partitions !== "all") {
+    if (!Array.isArray(partitions) || partitions.length === 0 || partitions.length > 1000 || !partitions.every((item) => typeof item === "string" && item !== "" && item.length <= 200)) return "config.partitions must be none, all or a list of partitions";
+  }
+  return null;
+}
+
+/** An event start; its expressions are checked with the whole document. */
+function eventStart(config: Record<string, unknown>): string | null {
+  const { debounce } = config;
+  if (debounce !== undefined) {
+    if (typeof debounce !== "object" || debounce === null || Array.isArray(debounce)) return "config.debounce must be an object";
+    const { key } = debounce as { key?: unknown };
+    if (key === undefined) return "config.debounce.key is required";
+    const problem = string(debounce as Record<string, unknown>, "window", ISO_DURATION);
+    if (problem !== null) return problem.replace("config.", "config.debounce.");
+  }
+  return first(string(config, "event", DOTTED_KEY), string(config, "delay", ISO_DURATION, false), boolean(config, "ignoreOwn"));
 }
 
 /** A timer: either `duration` (ISO 8601) or `at`, a path to a date in instance data. */
@@ -115,6 +154,29 @@ function assignments(config: Record<string, unknown>): string | null {
   return null;
 }
 
+/** What a loop runs over and how; its expressions are checked with the whole document. */
+function loop(config: Record<string, unknown>): string | null {
+  const sources = ["over", "while", "times"].filter((key) => config[key] !== undefined);
+  if (sources.length !== 1) return "config needs exactly one of over, while or times";
+  const { maxIterations, times, parallel, onItemError: onItem, collect } = config;
+  if (!Number.isSafeInteger(maxIterations) || (maxIterations as number) < 1 || (maxIterations as number) > MAX_ITERATIONS) return `config.maxIterations must be 1–${MAX_ITERATIONS}`;
+  if (times !== undefined && (!Number.isSafeInteger(times) || (times as number) < 1 || (times as number) > (maxIterations as number))) return "config.times must be an integer from 1 to maxIterations";
+  if (parallel !== undefined) {
+    if (typeof parallel !== "object" || parallel === null || Array.isArray(parallel)) return "config.parallel must be an object";
+    const { limit } = parallel as { limit?: unknown };
+    if (!Number.isSafeInteger(limit) || (limit as number) < 1 || (limit as number) > MAX_LOOP_PARALLEL) return `config.parallel.limit must be 1–${MAX_LOOP_PARALLEL}`;
+    if (config.while !== undefined) return "config.parallel does not go with while: its condition depends on the iteration before";
+  }
+  if (onItem !== undefined && onItem !== "stop" && onItem !== "skip") return "config.onItemError must be stop or skip";
+  if (collect !== undefined) {
+    if (typeof collect !== "object" || collect === null || Array.isArray(collect)) return "config.collect must be an object";
+    const { from, to } = collect as { from?: unknown; to?: unknown };
+    if (from === undefined) return "config.collect.from is required";
+    if (typeof to !== "string" || !FIELD_NAME.test(to)) return "config.collect.to is invalid";
+  }
+  return first(string(config, "item", FIELD_NAME, false), string(config, "index", FIELD_NAME, false));
+}
+
 const duration = { type: "string", format: "duration" };
 const text = { type: "string" };
 const dataPath = { type: "string", pattern: DATA_PATH.source };
@@ -127,8 +189,32 @@ const fields = { type: "object", properties: { fields: { type: "array", items: {
 
 export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
   { kind: "manualStart", role: "start", check: none, config: object({}) },
-  { kind: "scheduleStart", role: "start", check: cron, config: object({ cron: text }, ["cron"]) },
-  { kind: "eventStart", role: "start", check: (c) => string(c, "event", DOTTED_KEY), config: object({ event: text }, ["event"]) },
+  {
+    kind: "scheduleStart",
+    role: "start",
+    check: schedule,
+    config: object({
+      cron: text,
+      timezone: { type: "string", description: "An IANA time zone; UTC by default" },
+      from: { type: "string", format: "date-time" },
+      until: { type: "string", format: "date-time" },
+      overlap: { enum: ["skip", "queue", "parallel"] },
+      catchUp: flag,
+      partitions: { description: "none, all or a list of partitions", oneOf: [{ enum: ["none", "all"] }, { type: "array", items: text }] },
+    }, ["cron"]),
+  },
+  {
+    kind: "eventStart",
+    role: "start",
+    check: eventStart,
+    config: object({
+      event: text,
+      filter: expression,
+      debounce: object({ key: expression, window: duration }, ["key", "window"]),
+      delay: duration,
+      ignoreOwn: flag,
+    }, ["event"]),
+  },
   {
     kind: "userTask",
     role: "activity",
@@ -154,12 +240,40 @@ export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
     check: assignments,
     config: object({ assignments: { type: "array", minItems: 1, items: object({ var: { type: "string", pattern: FIELD_NAME.source }, value: expression }, ["var", "value"]) } }, ["assignments"]),
   },
+  {
+    kind: "loop",
+    role: "activity",
+    container: true,
+    check: loop,
+    config: object({
+      over: expression,
+      while: expression,
+      times: { type: "integer", minimum: 1, maximum: MAX_ITERATIONS },
+      item: saveTo,
+      index: saveTo,
+      maxIterations: { type: "integer", minimum: 1, maximum: MAX_ITERATIONS },
+      parallel: object({ limit: { type: "integer", minimum: 1, maximum: MAX_LOOP_PARALLEL } }, ["limit"]),
+      onItemError: { enum: ["stop", "skip"] },
+      collect: object({ from: expression, to: saveTo }, ["from", "to"]),
+    }, ["maxIterations"]),
+  },
+  {
+    kind: "callProcess",
+    role: "activity",
+    check: (c) => first(string(c, "process", PROCESS_KEY), inputMapping(c), string(c, "saveTo", FIELD_NAME, false), onError(c)),
+    config: object({
+      process: { type: "string", pattern: PROCESS_KEY.source },
+      input: { type: "object", description: "Parameter → a literal, a path string or an expression" },
+      saveTo,
+      onError: { enum: ["fail", "skip"] },
+    }, ["process"]),
+  },
   { kind: "timerCatch", role: "activity", check: timer, config: object(timerConfig) },
   {
     kind: "eventWait",
     role: "activity",
     check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), string(c, "saveTo", FIELD_NAME, false)),
-    config: object({ event: text, correlation: dataPath, saveTo }, ["event"]),
+    config: object({ event: text, correlation: dataPath, saveTo, until: expression }, ["event"]),
   },
   { kind: "exclusiveGateway", role: "gateway", check: none, config: object({}) },
   { kind: "parallelGateway", role: "gateway", check: none, config: object({}) },

package/library/workflow/palette.ts

@@ -17,6 +17,8 @@ export interface PaletteTool {
 export interface PaletteNodeKind {
   readonly kind: NodeKind;
   readonly role: NodeRole;
+  /** A container: other nodes name it as their `parent`. */
+  readonly container?: boolean;
   readonly config: JsonSchema;
 }
 
@@ -31,7 +33,7 @@ export interface ProcessPalette {
 /** The palette with the application's Tools: a new Tool appears in a designer without a release of the framework. */
 export function processPalette(tools: readonly PaletteTool[]): ProcessPalette {
   return {
-    nodeKinds: NODE_KINDS.map(({ kind, role, config }) => ({ kind, role, config })),
+    nodeKinds: NODE_KINDS.map(({ kind, role, container, config }) => ({ kind, role, ...(container === undefined ? {} : { container }), config })),
     functions: EXPRESSION_FUNCTIONS,
     paths: DATA_PATHS,
     tools,

package/library/workflow/paths.ts

@@ -10,16 +10,20 @@ export interface InstanceData {
   readonly nodes: Readonly<Record<string, unknown>>;
   /** The data of the event that started or continued the process. */
   readonly event?: unknown;
-  /** How it was started: `{ via, at, actor, eventKey?, cause? }`. */
+  /** How it was started: `{ via, at, actor, eventKey?, cause?, scheduledAt? }`. */
   readonly trigger?: unknown;
   /** `{ id, processKey, version, partition, test }`. */
   readonly run?: unknown;
   /** The engine's time as an ISO string. */
   readonly now?: string;
+  /** Inside a loop body: the element of this iteration. */
+  readonly item?: unknown;
+  /** Inside a loop body: the number of this iteration, from 0. */
+  readonly index?: number;
 }
 
-/** `$input.amount`, `$vars.payment.id`, `$nodes.Pay.paymentId`, `$event.record.id`, `$run.partition`, `$now`. */
-export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
+/** `$input.amount`, `$vars.payment.id`, `$nodes.Pay.paymentId`, `$event.record.id`, `$run.partition`, `$now`, `$item.id`, `$index`. */
+export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now|item|index)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
 
 /** The roots of `$` paths, for a designer. */
 export const DATA_PATHS: readonly { readonly path: string; readonly description: string }[] = Object.freeze([
@@ -27,9 +31,11 @@ export const DATA_PATHS: readonly { readonly path: string; readonly description:
   { path: "$vars.<name>", description: "A variable of the process" },
   { path: "$nodes.<node>.<field>", description: "The result of a passed step" },
   { path: "$event", description: "The data of the event that started or continued the process" },
-  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause? }" },
+  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause?, scheduledAt? }" },
   { path: "$run", description: "This run: { id, processKey, version, partition, test }" },
   { path: "$now", description: "The engine's time" },
+  { path: "$item", description: "Inside a loop body: the element of this iteration" },
+  { path: "$index", description: "Inside a loop body: the number of this iteration, from 0" },
 ]);
 
 /** `true` if the value is a path to instance data. */

package/library/workflow/structure.ts

@@ -30,8 +30,20 @@ export interface StructureBoundary {
   readonly exitTitle?: LocalizedText;
 }
 
-/** A step of the list: a single node, an exclusive fork or a parallel block. */
+/** A step of the list: a single node, a loop around a list, an exclusive fork or a parallel block. */
 export type StructureStep =
+  | {
+    readonly type: "loop";
+    readonly id: string;
+    readonly node: ProcessNode;
+    /** The steps of an iteration. */
+    readonly body: readonly StructureStep[];
+    /** The end of the body. */
+    readonly bodyEnd: { readonly id: string; readonly node: ProcessNode };
+    readonly boundaries?: readonly StructureBoundary[];
+    readonly next: string;
+    readonly nextTitle?: LocalizedText;
+  }
   | {
     readonly type: "step";
     readonly id: string;
@@ -141,7 +153,8 @@ class Reader {
         this.visit(current);
         const [flowId, flow] = this.single(current);
         const boundaries = (this.boundaries.get(current) ?? []).map(([id, boundary]) => this.boundary(id, boundary, flow.target));
-        steps.push({ type: "step", id: current, node, ...(boundaries.length === 0 ? {} : { boundaries }), next: flowId, ...(flow.title === undefined ? {} : { nextTitle: flow.title }) });
+        const common = { id: current, node, ...(boundaries.length === 0 ? {} : { boundaries }), next: flowId, ...(flow.title === undefined ? {} : { nextTitle: flow.title }) };
+        steps.push(node.kind === "loop" ? { type: "loop", ...common, ...this.body(current) } : { type: "step", ...common });
         exit = { flow: flowId, ...(flow.title === undefined ? {} : { title: flow.title }) };
         current = flow.target;
         continue;
@@ -158,6 +171,18 @@ class Reader {
     }
   }
 
+  /** The body of a loop: a list from its one entry to its one end. */
+  private body(loop: string): { readonly body: StructureStep[]; readonly bodyEnd: { readonly id: string; readonly node: ProcessNode } } {
+    const members = Object.entries(this.document.nodes).filter(([, node]) => node.parent === loop && node.attachedTo === undefined);
+    const entries = members.filter(([id]) => (this.incoming.get(id)?.length ?? 0) === 0);
+    if (entries.length !== 1) throw new NotStructured();
+    const { steps, stop } = this.sequence(entries[0]![0]);
+    const end = this.node(stop);
+    if (nodeKindOf(end.kind)?.role !== "end" || end.parent !== loop || steps.length === 0) throw new NotStructured();
+    this.visited.add(stop);
+    return { body: steps, bodyEnd: { id: stop, node: end } };
+  }
+
   private fork(id: string, node: ProcessNode, outs: readonly (readonly [string, ProcessFlow])[]): { readonly step: Extract<StructureStep, { type: "choice" | "parallel" }>; readonly stop: string } {
     if ((this.incoming.get(id)?.length ?? 0) !== 1) throw new NotStructured();
     this.visit(id);
@@ -207,7 +232,7 @@ class Reader {
 /**
  * A graph as a tree of steps, or `undefined` when it is outside the subset a
  * list can draw (WORKFLOW-002 §3.6): sequences, an exclusive gateway with one
- * merge, a parallel gateway with a join, boundary events on steps.
+ * merge, a parallel gateway with a join, a loop, boundary events on steps.
  */
 export function toStructure(document: ProcessDocument): ProcessStructure | undefined {
   try {
@@ -242,9 +267,13 @@ export function fromStructure(structure: ProcessStructure): ProcessDocument {
       const target = index + 1 < list.length ? list[index + 1]!.id : after;
       const last = index + 1 === list.length && leave !== undefined;
       nodes[step.id] = step.node;
-      if (step.type === "step") {
+      if (step.type === "step" || step.type === "loop") {
         flow(last ? leave.flow : step.next, step.id, target, titled(last ? leave.title : step.nextTitle));
         for (const boundary of step.boundaries ?? []) writeBoundary(boundary, step, target);
+        if (step.type === "loop") {
+          write(step.body, step.bodyEnd.id);
+          nodes[step.bodyEnd.id] = step.bodyEnd.node;
+        }
         return;
       }
       const meet = step.merge?.id ?? target;