bazis 0.132.0 → 0.133.0

package/core/workflow/runtime_module/internal/WorkflowJobs.ts

@@ -2,6 +2,8 @@ import type { ServiceProvider } from "../../../di";
 import { WorkflowClock } from "../../contracts/WorkflowClock";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
+import { ChildCalls } from "./ChildCalls";
+import { RunLimits } from "./RunLimits";
 import { Schedules } from "./Schedules";
 import { TimerStep } from "./TimerStep";
 import { LEASE_MS, ToolStep } from "./ToolStep";
@@ -31,7 +33,7 @@ export class WorkflowJobs {
       const now = scope.resolve(WorkflowClock).now();
       return await db.transactionScope(async () => {
         const jobs = await db.jobs
-          .where((j) => j.kind.in(["tool", "timer", "schedule"]).and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
+          .where((j) => j.dueAt.lte(now).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
           .orderBy((j) => j.id)
           .take(batchSize)
           .forUpdate({ skipLocked: true })
@@ -51,9 +53,37 @@ export class WorkflowJobs {
   async run(job: WfJob, signal: AbortSignal): Promise<void> {
     const scope = this.services.createScope();
     try {
-      if (job.kind === "timer") await scope.resolve(TimerStep).run(job);
-      else if (job.kind === "schedule") await scope.resolve(Schedules).fire(job);
-      else await scope.resolve(ToolStep).run(job, signal);
+      switch (job.kind) {
+        case "timer":
+          await scope.resolve(TimerStep).run(job);
+          break;
+        case "loop":
+          await scope.resolve(TimerStep).continueLoop(job);
+          break;
+        case "schedule":
+          await scope.resolve(Schedules).fire(job);
+          break;
+        case "call":
+          await scope.resolve(ChildCalls).call(job);
+          break;
+        case "returned":
+          await scope.resolve(ChildCalls).returned(job);
+          break;
+        case "cancelChildren":
+          await scope.resolve(ChildCalls).cancelChildren(job);
+          break;
+        case "runTimeout":
+          await scope.resolve(RunLimits).runTimeout(job);
+          break;
+        case "release":
+          await scope.resolve(RunLimits).release(job);
+          break;
+        case "errorHandler":
+          await scope.resolve(RunLimits).errorHandler(job);
+          break;
+        default:
+          await scope.resolve(ToolStep).run(job, signal);
+      }
     } catch (error) {
       this.report("job failed", error, { job: job.id, instance: job.instanceId, attempts: job.attempts });
       await this.giveUpOrDelay(job, error).catch((failure: unknown) => this.report("job failure handling failed", failure, { job: job.id }));
@@ -62,11 +92,12 @@ export class WorkflowJobs {
     }
   }
 
-  /** Matches the scheduled starts against the published versions. */
+  /** Matches the scheduled starts against the published versions and gives a free place to whoever still waits for one. */
   async reconcile(): Promise<void> {
     const scope = this.services.createScope();
     try {
       await scope.resolve(Schedules).reconcile();
+      await scope.resolve(RunLimits).releaseWaiting();
     } catch (error) {
       this.report("scheduled starts could not be planned", error);
     } finally {
@@ -89,7 +120,7 @@ export class WorkflowJobs {
       await engine.inStep(job.instanceId, async (step) => {
         await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
         const token = step.tokens.find((t) => t.id === job.tokenId);
-        if (token && token.status === "waiting" && step.instance.status === "running") engine.fail(step, token, "job_failed", message.slice(0, 1000));
+        if (token && token.status === "waiting" && step.instance.status === "running") await engine.fail(step, token, "job_failed", message.slice(0, 1000));
       });
     } finally {
       await scope.dispose();

package/core/workflow/runtime_module/model/WfHistory.model.ts

@@ -1,7 +1,7 @@
 import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
 import { WfInstance } from "./WfInstance.model";
 
-export type HistoryType = "started" | "entered" | "left" | "tool" | "assigned" | "skipped" | "timer" | "event" | "error" | "retried" | "cancelled" | "completed";
+export type HistoryType = "started" | "queued" | "released" | "entered" | "left" | "tool" | "assigned" | "iteration" | "called" | "returned" | "skipped" | "timer" | "event" | "error" | "retried" | "cancelled" | "timedOut" | "handler" | "completed";
 
 /** The journal of an instance, append only. Its v7 ids give the order. */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })

package/core/workflow/runtime_module/model/WfInstance.model.ts

@@ -1,9 +1,12 @@
 import { Column, Entity, Index, UUID } from "../../../orm";
 
-/** `completed` and `cancelled` are finished: retention deletes them. `failed` waits for retry or cancel. */
-export type InstanceStatus = "running" | "completed" | "cancelled" | "failed";
+/**
+ * `completed`, `cancelled` and `timedOut` are finished: retention deletes them.
+ * `failed` waits for retry or cancel, `pending` for a free place (`maxConcurrent`, `sameKey: "queue"`).
+ */
+export type InstanceStatus = "pending" | "running" | "completed" | "cancelled" | "failed" | "timedOut";
 
-export type StartedVia = "manual" | "event" | "schedule";
+export type StartedVia = "manual" | "event" | "schedule" | "callProcess" | "errorHandler";
 
 /**
  * One run of a process. Bound to the version it started with: a new publication
@@ -62,7 +65,7 @@ export class WfInstance {
   @Column({ type: "boolean" })
   test = false;
 
-  /** The instance whose `callProcess` started this one (stage 3). */
+  /** The instance whose `callProcess` started this one, and the waiting token there. */
   @Index()
   @Column({ type: "text", nullable: true })
   parentInstanceId: string | null = null;

package/core/workflow/runtime_module/model/WfJob.model.ts

@@ -1,12 +1,21 @@
 import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
 import { WfInstance } from "./WfInstance.model";
 
-/** `tool` calls a service task's Tool; `timer`, `retry` and `schedule` come with their stages. */
-export type JobKind = "tool" | "timer" | "retry" | "schedule";
+/**
+ * `tool` calls a service task's Tool, `timer` fires a timer, `schedule` starts a
+ * scheduled process, `loop` goes on with a loop after a batch of iterations.
+ * `call` starts a called process, `returned` tells the caller it ended,
+ * `cancelChildren` closes what a closed step called. `runTimeout` ends a run that
+ * took too long, `release` starts instances that wait for a place, `errorHandler`
+ * starts the process that handles a failure.
+ */
+export type JobKind = "tool" | "timer" | "schedule" | "loop" | "call" | "returned" | "cancelChildren" | "runTimeout" | "release" | "errorHandler";
 
 /**
  * Deferred work of the worker, created in the same transaction as the waiting
- * token. Application instances claim it with `FOR UPDATE SKIP LOCKED`.
+ * token. Application instances claim it with `FOR UPDATE SKIP LOCKED`. A
+ * transaction holds the row of one instance only: what another instance must do
+ * goes through a job, so that two instances never wait for each other.
  */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
 @Entity({ table: "bazis_wf2_run_jobs" })
@@ -34,7 +43,7 @@ export class WfJob {
   @Column({ type: "datetime" })
   dueAt = new Date(0);
 
-  /** What a job carries besides its token: an event to deliver (stage 4). */
+  /** What a job carries besides its token: the caller to tell, the process to release. */
   @Column({ type: "json", nullable: true })
   payload: unknown = null;
 

package/core/workflow/runtime_module/model/WfToken.model.ts

@@ -2,8 +2,9 @@ import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
 import { WfInstance } from "./WfInstance.model";
 
 /**
- * `active` passes a node, `waiting` waits for a Tool, a task or a join, `done`
- * moved on, `cancelled` was closed by a cancel, `failed` waits for a retry.
+ * `active` passes a node, `waiting` waits for a Tool, a task, a join, a loop or a
+ * called process, `done` moved on, `cancelled` was closed by a cancel, `failed`
+ * waits for a retry.
  */
 export type TokenStatus = "active" | "waiting" | "done" | "cancelled" | "failed";
 
@@ -28,10 +29,11 @@ export class WfToken {
   @Column({ type: "text" })
   status: TokenStatus = "active";
 
+  /** A step's result; a loop keeps its progress here while it runs. */
   @Column({ type: "json", nullable: true })
   output: unknown = null;
 
-  /** The loop token this one runs inside, with its iteration and what only the body sees (stage 3). */
+  /** The loop token this one runs inside, with its iteration and what only the body sees: `Locals` of the engine. */
   @Column({ type: "text", nullable: true })
   parentTokenId: string | null = null;
 

package/core/workflow/runtime_module/services/IWorkflowRuntime.service.ts

@@ -17,6 +17,30 @@ export interface StartInstance extends WorkflowAuditOptions {
   readonly language?: string;
 }
 
+/** One element of a mass start. */
+export interface StartManyItem {
+  readonly input?: unknown;
+  /** What the instance is about: required, it is what `sameKey` compares. */
+  readonly businessKey: string;
+}
+
+export interface StartMany extends WorkflowAuditOptions {
+  readonly items: readonly StartManyItem[];
+  readonly partition?: string | null;
+  readonly actor: WorkflowActor;
+  readonly language?: string;
+}
+
+/**
+ * What became of one element: `started` (the instance may wait as `pending`),
+ * `skipped` (`sameKey: "skip"` and `instanceId` is the unfinished one) or `rejected`
+ * (no `businessKey`, invalid input).
+ */
+export type StartManyResult =
+  | { readonly status: "started"; readonly businessKey: string; readonly instanceId: string; readonly instanceStatus: InstanceStatus }
+  | { readonly status: "skipped"; readonly businessKey: string; readonly instanceId: string; readonly reason: "same_key" }
+  | { readonly status: "rejected"; readonly businessKey: string | null; readonly reason: "business_key_required" | "invalid_input"; readonly issues?: readonly FormIssue[] };
+
 export interface CancelInstance extends WorkflowAuditOptions {
   readonly reason?: string | null;
   readonly actor: WorkflowActor;
@@ -35,6 +59,8 @@ export interface InstanceSummary {
   readonly businessKey: string | null;
   readonly startedVia: StartedVia;
   readonly startedBy: WorkflowActor;
+  /** The instance whose `callProcess` started this one. */
+  readonly parentInstanceId: string | null;
   readonly error: { readonly node: string; readonly code: string; readonly message: string } | null;
   readonly createdAt: Date;
   readonly endedAt: Date | null;
@@ -44,6 +70,9 @@ export interface TokenDetails {
   readonly id: string;
   readonly nodeId: string;
   readonly viaFlowId: string | null;
+  /** Inside a loop body: the token of the loop and the number of the iteration. */
+  readonly parentTokenId: string | null;
+  readonly iteration: number | null;
   readonly status: TokenStatus;
   readonly output: unknown;
   readonly createdAt: Date;
@@ -82,6 +111,8 @@ export interface EmitOptions extends WorkflowAuditOptions {
 export interface EmitResult {
   /** Instances started by an `eventStart`. */
   readonly started: readonly string[];
+  /** Processes with `sameKey: "skip"` that did not start: an instance with the key is not finished. */
+  readonly skipped: readonly { readonly processKey: string; readonly instanceId: string }[];
   /** Instances whose `eventWait` or `boundaryEvent` took the event. */
   readonly continued: readonly string[];
   /** Processes with an `eventStart` whose input the payload did not pass. */
@@ -96,17 +127,21 @@ export interface InstanceListQuery extends WorkflowPaging {
   readonly processKey?: string;
   readonly businessKey?: string;
   readonly startedById?: string;
+  readonly parentInstanceId?: string;
 }
 
 /**
  * Runs published versions (WORKFLOW-001 §4). Errors are {@link WorkflowError}:
- * `not_found`, `archived`, `invalid_input` with the issues, `wrong_status`.
+ * `not_found`, `archived`, `invalid_input` with the issues, `wrong_status`,
+ * `conflict` when `sameKey: "skip"` refuses a start.
  */
 export abstract class IWorkflowRuntime {
-  /** Starts the latest version of a process from its manual start. */
+  /** Starts the latest version of a process from its manual start. It may wait as `pending` (`maxConcurrent`, `sameKey: "queue"`). */
   abstract start(processKey: string, options: StartInstance): Promise<InstanceDetails>;
+  /** Starts an instance per element, each in its own transaction, and says what became of each. */
+  abstract startMany(processKey: string, options: StartMany): Promise<readonly StartManyResult[]>;
   abstract cancel(instanceId: string, options: CancelInstance): Promise<InstanceDetails>;
-  /** Retries the failed steps of a `failed` instance. */
+  /** Retries the failed steps of a `failed` instance. An instance called by another one is retried through its caller. */
   abstract retry(instanceId: string, options: RetryInstance): Promise<InstanceDetails>;
   /** Finishes a user task's wait with the form output and moves on; `wrong_status` when the token no longer waits. */
   abstract completeToken(tokenId: string, output: unknown, actor: WorkflowActor, options?: { readonly language?: string }): Promise<InstanceDetails>;

package/core/workflow/runtime_module/services/WorkflowRuntime.service.ts

@@ -23,9 +23,12 @@ import {
   type InstanceSummary,
   type RetryInstance,
   type StartInstance,
+  type StartMany,
+  type StartManyResult,
 } from "./IWorkflowRuntime.service";
 
-const STATUSES = new Set(["running", "completed", "cancelled", "failed"]);
+const STATUSES = new Set(["pending", "running", "completed", "cancelled", "failed", "timedOut"]);
+const MAX_START_MANY = 1000;
 const EVENT_KEY = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$/;
 
 export class WorkflowRuntime extends IWorkflowRuntime {
@@ -49,16 +52,48 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
     const { value, issues } = await this.validator().validate(inputSpecOf(version.document), options.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
     if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
-    const id = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
+    const { id, skipped } = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
+    if (skipped) throw new WorkflowError("conflict", `Instance ${id} with this businessKey is not finished`);
     return await this.instance(id);
   }
 
+  async startMany(processKey: string, options: StartMany): Promise<readonly StartManyResult[]> {
+    actorOf(options.actor);
+    const partition = optionalText(options.partition, "partition");
+    if (!Array.isArray(options.items) || options.items.length === 0 || options.items.length > MAX_START_MANY) throw new WorkflowError("invalid_input", `items must be a list of 1–${MAX_START_MANY}`);
+    const version = await this.definitions.latest(processKey);
+    const start = Object.entries(version.document.nodes).find(([, node]) => node.kind === "manualStart");
+    if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
+    const graph = this.engine.cache(version);
+    const results: StartManyResult[] = [];
+    for (const item of options.items) {
+      const businessKey = typeof item?.businessKey === "string" && item.businessKey !== "" && item.businessKey.length <= 200 ? item.businessKey : null;
+      if (businessKey === null) {
+        results.push({ status: "rejected", businessKey: null, reason: "business_key_required" });
+        continue;
+      }
+      const { value, issues } = await this.validator().validate(inputSpecOf(version.document), item.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
+      if (issues.length > 0) {
+        results.push({ status: "rejected", businessKey, reason: "invalid_input", issues });
+        continue;
+      }
+      const { id, skipped } = await this.engine.begin(graph, start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
+      if (skipped) {
+        results.push({ status: "skipped", businessKey, instanceId: id, reason: "same_key" });
+        continue;
+      }
+      const row = await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(id));
+      results.push({ status: "started", businessKey, instanceId: id, instanceStatus: row?.status ?? "running" });
+    }
+    return results;
+  }
+
   async cancel(instanceId: string, options: CancelInstance): Promise<InstanceDetails> {
     actorOf(options.actor);
     const reason = optionalText(options.reason, "reason", 1000);
     if (!isUuid(instanceId)) throw notFound(instanceId);
     const done = await this.engine.inStep(instanceId, async (step) => {
-      if (step.instance.status !== "running" && step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Instance is ${step.instance.status}`);
+      if (step.instance.status !== "pending" && step.instance.status !== "running" && step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Instance is ${step.instance.status}`);
       await this.engine.cancel(step, reason, options.actor, options.request ?? null);
       return true;
     });
@@ -71,6 +106,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (!isUuid(instanceId)) throw notFound(instanceId);
     const done = await this.engine.inStep(instanceId, async (step) => {
       if (step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Only a failed instance is retried; this one is ${step.instance.status}`);
+      if (step.instance.parentInstanceId !== null) throw new WorkflowError("wrong_status", `This instance was called by ${step.instance.parentInstanceId}: retry that one`);
       await this.engine.retry(step, options.actor, options.request ?? null);
       return true;
     });
@@ -120,6 +156,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     }
 
     const started: string[] = [];
+    const skipped: { processKey: string; instanceId: string }[] = [];
     const rejected: { processKey: string; issues: readonly FormIssue[] }[] = [];
     for (const version of await this.definitions.published()) {
       for (const [nodeId, node] of Object.entries(version.document.nodes)) {
@@ -131,14 +168,16 @@ export class WorkflowRuntime extends IWorkflowRuntime {
           rejected.push({ processKey: version.key, issues });
           continue;
         }
-        started.push(await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null, event: { key: eventKey, payload: data } }));
+        const begun = await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null, event: { key: eventKey, payload: data } });
+        if (begun.skipped) skipped.push({ processKey: version.key, instanceId: begun.id });
+        else started.push(begun.id);
       }
     }
-    return { started, continued: [...continued], rejected };
+    return { started, skipped, continued: [...continued], rejected };
   }
 
   async instances(query: InstanceListQuery = {}): Promise<WorkflowPage<InstanceSummary>> {
-    if (query.status !== undefined && !STATUSES.has(query.status)) throw new WorkflowError("invalid_input", "status must be running, completed, cancelled or failed");
+    if (query.status !== undefined && !STATUSES.has(query.status)) throw new WorkflowError("invalid_input", "status must be pending, running, completed, cancelled, failed or timedOut");
     const where = query.access === undefined ? "all" : grantsToWhere(query.access);
     if (where === "none") return { items: [], total: 0 };
     let source = this.db.instances.asNoTracking();
@@ -148,6 +187,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (query.processKey !== undefined) source = source.where((i) => i.processKey.eq(query.processKey!));
     if (query.businessKey !== undefined) source = source.where((i) => i.businessKey.eq(query.businessKey!));
     if (query.startedById !== undefined) source = source.where((i) => i.startedById.eq(query.startedById!));
+    if (query.parentInstanceId !== undefined) source = source.where((i) => i.parentInstanceId.eq(query.parentInstanceId!));
     const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "desc" }));
     return { items: items.map(summaryOf), total };
   }
@@ -200,6 +240,7 @@ function summaryOf(row: WfInstance): InstanceSummary {
     businessKey: row.businessKey,
     startedVia: row.startedVia,
     startedBy: { kind: row.startedByKind, id: row.startedById },
+    parentInstanceId: row.parentInstanceId,
     error: row.error,
     createdAt: row.createdAt,
     endedAt: row.endedAt,
@@ -207,7 +248,7 @@ function summaryOf(row: WfInstance): InstanceSummary {
 }
 
 function tokenOf(row: WfToken) {
-  return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
+  return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, parentTokenId: row.parentTokenId, iteration: row.iteration, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
 }
 
 function historyOf(row: WfHistory): HistoryEntry {

package/core/workflow/tasks_module/events/TaskEvents.ts

@@ -1,5 +1,4 @@
 import { OnEvent } from "../../../kernel";
-import { UniqueViolationError } from "../../../orm";
 import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
 import type { TasksDbContext } from "../model/Tasks.dbContext";
 import { WfTask } from "../model/WfTask.model";
@@ -12,7 +11,8 @@ export class TaskEvents {
   @OnEvent(WORKFLOW_TASK_REQUESTED)
   async requested(event: WorkflowTaskRequested): Promise<void> {
     const assignee = "role" in event.assignee ? `role:${event.assignee.role}` : `user:${event.assignee.user}`;
-    this.db.tasks.add(Object.assign(new WfTask(), {
+    // Past the change tracker: the scope may go on to update tasks directly, which a context holding one would refuse.
+    await this.db.tasks.insertIfAbsent(Object.assign(new WfTask(), {
       tokenId: event.tokenId,
       instanceId: event.instanceId,
       processKey: event.processKey,
@@ -22,12 +22,8 @@ export class TaskEvents {
       assignee,
       form: event.form,
       dueAt: event.dueAt,
-    }));
-    try {
-      await this.db.saveChanges();
-    } catch (error) {
-      if (!(error instanceof UniqueViolationError)) throw error;
-    }
+      createdAt: new Date(),
+    }), { conflictBy: (t) => [t.tokenId] });
   }
 
   /** The step closed otherwise than by its task: the task is cancelled. */

package/core/workflow/tasks_module/services/WorkflowTasks.service.ts

@@ -93,7 +93,7 @@ export class WorkflowTasks extends IWorkflowTasks {
       if (error instanceof WorkflowError && error.code === "wrong_status") await this.close(task.tokenId, "cancelled");
       throw error;
     }
-    const saved = instance.nodes[task.nodeId];
+    const saved = instance.tokens.find((t) => t.id === task.tokenId)?.output;
     await this.db.tasks.asNoTracking().where((t) => t.id.eq(task.id)).executeUpdate({
       status: "completed",
       completedById: actor.id,

package/library/workflow/ProcessDocument.ts

@@ -18,6 +18,8 @@ export type NodeKind =
   | "userTask"
   | "serviceTask"
   | "assign"
+  | "loop"
+  | "callProcess"
   | "timerCatch"
   | "eventWait"
   | "exclusiveGateway"
@@ -32,6 +34,8 @@ export interface ProcessNode {
   readonly title: LocalizedText;
   /** Boundary nodes only: the step the node is attached to. */
   readonly attachedTo?: string;
+  /** The `loop` whose body the node belongs to. */
+  readonly parent?: string;
   readonly config?: Readonly<Record<string, unknown>>;
   /** The application's data by namespace; the engine does not read it. */
   readonly extensions?: Readonly<Record<string, unknown>>;
@@ -77,8 +81,18 @@ export interface ProcessLogSettings {
 
 /** Settings of a process: they are part of the version. */
 export interface ProcessSettings {
+  /** On whose behalf steps run: who started the instance (the default) or the process's own system actor. */
+  readonly runAs?: "starter" | "process";
+  /** How long the whole run may take, waits included: an ISO duration. */
+  readonly runTimeout?: string;
   /** The default `timeout` of steps with a Tool: an ISO duration. */
   readonly stepTimeout?: string;
+  /** How many instances of the process run at once; the rest wait as `pending`. */
+  readonly maxConcurrent?: number;
+  /** A new start with the `businessKey` of an unfinished instance: run as well, do not start, or wait for it. */
+  readonly sameKey?: "allow" | "skip" | "queue";
+  /** The key of the process to start when an instance fails or times out. */
+  readonly errorHandler?: string;
   readonly log?: ProcessLogSettings;
 }
 

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, 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 {

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":