bazis 0.131.0 → 0.133.0

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

@@ -2,13 +2,13 @@ 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 { ToolStep } from "./ToolStep";
+import { LEASE_MS, ToolStep } from "./ToolStep";
 import { WorkflowEngine } from "./WorkflowEngine";
 
-/** How long a claimed job belongs to its worker; if it dies, another one takes the job after that. */
-const LEASE_MS = 5 * 60_000;
 /** A job that keeps failing outside its Tool (the database, a lost version) fails its step after this many tries. */
 const MAX_JOB_ATTEMPTS = 5;
 
@@ -16,7 +16,7 @@ const MAX_JOB_ATTEMPTS = 5;
 export type JobFailureReport = (message: string, error: unknown, fields?: Readonly<Record<string, unknown>>) => void;
 
 /**
- * Claiming and running jobs of `bazis_wf_run_jobs`: the work of the worker, and
+ * Claiming and running jobs of `bazis_wf2_run_jobs`: the work of the worker, and
  * of `drain` in tests. Every job runs in its own DI scope.
  */
 export class WorkflowJobs {
@@ -33,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 })
@@ -53,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 }));
@@ -64,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 {
@@ -91,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/Runtime.dbContext.ts

@@ -19,7 +19,7 @@ export const RUNTIME_ENTITIES = [WfInstance, WfToken, WfJob, WfSubscription, WfH
 /** The tables of the Runtime part: bazis creates and checks them in the application database. */
 export const runtimeStore = defineOrmOwnedStoreV1({
   contract: "bazis.orm-owned-store/v1",
-  storeKey: "bazis.workflow.runtime",
+  storeKey: "bazis.workflow.runtime.v2",
   formatVersion: 1,
-  ownedScope: { schema: "public", tablePrefix: "bazis_wf_run_" },
+  ownedScope: { schema: "public", tablePrefix: "bazis_wf2_run_" },
 });

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

@@ -1,12 +1,12 @@
 import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
 import { WfInstance } from "./WfInstance.model";
 
-export type HistoryType = "started" | "entered" | "left" | "tool" | "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" })
 @Index(["instanceId", "id"])
-@Entity({ table: "bazis_wf_run_history" })
+@Entity({ table: "bazis_wf2_run_history" })
 export class WfHistory {
   @UUID({ version: "v7" })
   id = "";

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

@@ -1,19 +1,23 @@
 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
- * does not touch it. Its data: the input, the variables `saveTo` writes and the
- * result of each step by node id.
+ * does not touch it. Its data: the input, the variables and the result of each
+ * step by node id.
  */
 @Index(["partition", "status"])
 @Index(["processKey", "status"])
 @Index(["status", "endedAt"])
-@Entity({ table: "bazis_wf_run_instances" })
+@Index(["test", "createdAt"])
+@Entity({ table: "bazis_wf2_run_instances" })
 export class WfInstance {
   @UUID({ version: "v7" })
   id = "";
@@ -45,6 +49,30 @@ export class WfInstance {
   @Column({ type: "json" })
   nodes: Record<string, unknown> = {};
 
+  /** What the process gave back: its `out` variables when it completed. */
+  @Column({ type: "json", nullable: true })
+  output: Record<string, unknown> | null = null;
+
+  /** `$event`: the data of the event that started or last continued it. */
+  @Column({ type: "json", nullable: true })
+  event: unknown = null;
+
+  /** `$trigger`: how it was started. */
+  @Column({ type: "json", nullable: true })
+  trigger: Record<string, unknown> | null = null;
+
+  /** A trial run (WORKFLOW-002 §5.4, stage 5). */
+  @Column({ type: "boolean" })
+  test = false;
+
+  /** The instance whose `callProcess` started this one, and the waiting token there. */
+  @Index()
+  @Column({ type: "text", nullable: true })
+  parentInstanceId: string | null = null;
+
+  @Column({ type: "text", nullable: true })
+  parentTokenId: string | null = null;
+
   @Index()
   @Column({ type: "text", nullable: true })
   businessKey: string | null = null;

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

@@ -1,15 +1,24 @@
 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_wf_run_jobs" })
+@Entity({ table: "bazis_wf2_run_jobs" })
 export class WfJob {
   @UUID({ version: "v7" })
   id = "";
@@ -34,6 +43,22 @@ export class WfJob {
   @Column({ type: "datetime" })
   dueAt = new Date(0);
 
+  /** What a job carries besides its token: the caller to tell, the process to release. */
+  @Column({ type: "json", nullable: true })
+  payload: unknown = null;
+
+  /** Jobs with one key merge into the last: `debounce` of an event start (stage 4). */
+  @Index()
+  @Column({ type: "text", nullable: true })
+  dedupeKey: string | null = null;
+
+  /** The partition and the start node of a `schedule` job (stage 4). */
+  @Column({ type: "text", nullable: true })
+  partition: string | null = null;
+
+  @Column({ type: "text", nullable: true })
+  nodeId: string | null = null;
+
   @Column({ type: "integer" })
   attempts = 0;
 

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

@@ -4,7 +4,7 @@ import { WfInstance } from "./WfInstance.model";
 /** A token waiting for an event: `eventWait` or `boundaryEvent`. Matched by key and correlation. */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
 @Index(["eventKey", "correlation"])
-@Entity({ table: "bazis_wf_run_subscriptions" })
+@Entity({ table: "bazis_wf2_run_subscriptions" })
 export class WfSubscription {
   @UUID({ version: "v7" })
   id = "";

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

@@ -2,15 +2,16 @@ 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";
 
 /** Where execution is. After a parallel gateway an instance has several. Its id is the idempotency key of a Tool call. */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
 @Index(["instanceId", "status"])
-@Entity({ table: "bazis_wf_run_tokens" })
+@Entity({ table: "bazis_wf2_run_tokens" })
 export class WfToken {
   @UUID({ version: "v7" })
   id = "";
@@ -28,9 +29,20 @@ 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: `Locals` of the engine. */
+  @Column({ type: "text", nullable: true })
+  parentTokenId: string | null = null;
+
+  @Column({ type: "integer", nullable: true })
+  iteration: number | null = null;
+
+  @Column({ type: "json", nullable: true })
+  locals: Record<string, unknown> | null = null;
+
   @Column({ type: "createdAt" })
   createdAt = new Date(0);
 

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

@@ -13,8 +13,34 @@ export interface StartInstance extends WorkflowAuditOptions {
   readonly businessKey?: string | null;
   /** On whose behalf the steps run. */
   readonly actor: WorkflowActor;
+  /** The language of the request, for the application's validator; `workflow.language` by default. */
+  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;
@@ -33,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;
@@ -42,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;
@@ -52,6 +83,8 @@ export interface InstanceDetails extends InstanceSummary {
   readonly input: Record<string, unknown>;
   readonly vars: Record<string, unknown>;
   readonly nodes: Record<string, unknown>;
+  /** What the process gave back: its `out` variables; `null` until it completes. */
+  readonly output: Record<string, unknown> | null;
   /** Every token, oldest first. */
   readonly tokens: readonly TokenDetails[];
 }
@@ -78,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. */
@@ -92,20 +127,24 @@ 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): Promise<InstanceDetails>;
+  abstract completeToken(tokenId: string, output: unknown, actor: WorkflowActor, options?: { readonly language?: string }): Promise<InstanceDetails>;
   /**
    * Delivers an event: starts processes whose latest version has an
    * `eventStart` for the key, and moves the instances waiting for it.

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

@@ -1,11 +1,12 @@
 import { grantsToWhere } from "../../../access";
 import { paginate } from "../../../orm";
-import type { FormIssue, FormSpec } from "../../../../library/workflow";
+import { inputSpecOf, type FormIssue, type FormSpec } from "../../../../library/workflow";
 import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import type { ServiceProvider } from "../../../di";
 import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
 import type { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { WorkflowEngine } from "../internal/WorkflowEngine";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfHistory } from "../model/WfHistory.model";
@@ -22,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 {
@@ -34,6 +38,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     private readonly definitions: IWorkflowDefinitions,
     /** The scope: the input validator is asked here, so that the application's own registration replaces the default. */
     private readonly services: ServiceProvider,
+    private readonly languages: WorkflowLanguages,
   ) {
     super();
   }
@@ -45,18 +50,50 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     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 { value, issues } = await this.validator().validate(version.document.input, options.input, { purpose: "input", processKey, partition });
+    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;
     });
@@ -69,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;
     });
@@ -76,7 +114,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     return await this.instance(instanceId);
   }
 
-  async completeToken(tokenId: string, output: unknown, actor: WorkflowActor): Promise<InstanceDetails> {
+  async completeToken(tokenId: string, output: unknown, actor: WorkflowActor, options: { readonly language?: string } = {}): Promise<InstanceDetails> {
     actorOf(actor);
     if (!isUuid(tokenId)) throw new WorkflowError("not_found", `Token ${tokenId} does not exist`);
     const token = await this.db.tokens.asNoTracking().firstOrDefault((t) => t.id.eq(tokenId));
@@ -87,7 +125,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
       if (node?.kind !== "userTask" || !current || current.status !== "waiting" || step.instance.status !== "running") {
         throw new WorkflowError("wrong_status", "The token does not wait for a task");
       }
-      const { value, issues } = await this.validator().validate(node.config?.form as FormSpec | undefined, output, { purpose: "task", processKey: step.instance.processKey, partition: step.instance.partition });
+      const { value, issues } = await this.validator().validate(node.config?.form as FormSpec | undefined, output, { purpose: "task", processKey: step.instance.processKey, partition: step.instance.partition, language: options.language ?? this.languages.default, actor });
       if (issues.length > 0) throw new WorkflowError("invalid_input", "The task form is invalid", issues);
       await this.engine.complete(step, tokenId, value, actor);
       return true;
@@ -118,25 +156,28 @@ 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)) {
         if (node.kind !== "eventStart" || node.config?.event !== eventKey) continue;
         // An event carries more than a process needs: fields the input does not declare are dropped, not refused.
-        const { value, issues: all } = await this.validator().validate(version.document.input, data, { purpose: "input", processKey: version.key, partition });
+        const { value, issues: all } = await this.validator().validate(inputSpecOf(version.document), data, { purpose: "input", processKey: version.key, partition, language: this.languages.default, actor });
         const issues = all.filter((issue) => issue.code !== "unknown");
         if (issues.length > 0) {
           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 }));
+        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();
@@ -146,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 };
   }
@@ -155,7 +197,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     const row = await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(instanceId));
     if (!row) throw notFound(instanceId);
     const tokens = await this.db.tokens.asNoTracking().where((t) => t.instanceId.eq(instanceId)).orderBy((t) => t.id).toList();
-    return { ...summaryOf(row), input: row.input, vars: row.vars, nodes: row.nodes, tokens: tokens.map(tokenOf) };
+    return { ...summaryOf(row), input: row.input, vars: row.vars, nodes: row.nodes, output: row.output, tokens: tokens.map(tokenOf) };
   }
 
   async history(instanceId: string): Promise<readonly HistoryEntry[]> {
@@ -198,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,
@@ -205,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. */