bazis 0.131.0 → 0.133.0

package/core/workflow/index.ts

@@ -1,5 +1,5 @@
 /**
- * Business processes without a UI (WORKFLOW-001): the composite `WorkflowModule`
+ * Business processes without a UI (WORKFLOW-001, WORKFLOW-002): the composite `WorkflowModule`
  * with the Definitions and Runtime parts, their services, HTTP, events and
  * extension points. The document format is `bazis/library/workflow`.
  */
@@ -26,6 +26,7 @@ export {
   type SavedDraft,
   type SaveDraftOptions,
   type UpdateProcess,
+  type ValidateOptions,
   type VersionDetails,
   type VersionSummary,
 } from "./definitions_module/services/IWorkflowDefinitions.service";
@@ -58,11 +59,12 @@ export {
   type WorkflowTaskRequested,
   type WorkflowTokenClosed,
 } from "./runtime_module/events/Runtime.events";
-export { workflowRuntimeConfig } from "./runtime_module/config/Runtime.config";
+export { workflowConfig, type WorkflowSettings } from "./contracts/Workflow.config";
 export type { HistoryType } from "./runtime_module/model/WfHistory.model";
 export type { InstanceStatus, StartedVia } from "./runtime_module/model/WfInstance.model";
 export type { TokenStatus } from "./runtime_module/model/WfToken.model";
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
+export { WorkflowExtensions, DefaultWorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "./contracts/WorkflowExtensions";
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
 export type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging, WorkflowRequest, WorkflowToolMetadata } from "./contracts/types";
 

package/core/workflow/internal/WorkflowLanguages.ts

@@ -0,0 +1,35 @@
+import type { ConfigView } from "../../kernel";
+import type { WorkflowSettings } from "../contracts/Workflow.config";
+
+/**
+ * The language of a call (WORKFLOW-002 §6): over HTTP from `Accept-Language`
+ * among `workflow.languages`, otherwise `workflow.language`; in events, schedules
+ * and the background always `workflow.language`.
+ */
+export class WorkflowLanguages {
+  constructor(private readonly config: ConfigView<WorkflowSettings>) {}
+
+  get default(): string {
+    return this.config.get("language");
+  }
+
+  /** The best language of an `Accept-Language` header: by weight, then by order; `ru-RU` also finds `ru`. */
+  of(header: string | undefined): string {
+    if (header === undefined) return this.default;
+    const known = new Set([this.default, ...this.config.get("languages").split(",").map((item) => item.trim())]);
+    const wanted = header.split(",")
+      .map((part, index) => {
+        const [tag = "", ...parameters] = part.trim().split(";");
+        const weight = parameters.map((item) => /^\s*q=([\d.]+)\s*$/.exec(item)?.[1]).find((item) => item !== undefined);
+        return { tag: tag.trim(), weight: weight === undefined ? 1 : Number(weight), index };
+      })
+      .filter(({ tag, weight }) => tag !== "" && weight > 0)
+      .sort((a, b) => b.weight - a.weight || a.index - b.index);
+    for (const { tag } of wanted) {
+      if (known.has(tag)) return tag;
+      const base = tag.split("-")[0]!;
+      if (known.has(base)) return base;
+    }
+    return this.default;
+  }
+}

package/core/workflow/internal/canonicalJson.ts

@@ -0,0 +1,8 @@
+/** JSON with sorted keys: the same document gives the same hash whatever the key order. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object" && value !== null) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}

package/core/workflow/internal/http.ts

@@ -2,14 +2,28 @@ import { IAccess, type AccessObject, type SubjectAccess } from "../../access";
 import { ForbiddenError, type HttpContext } from "../../http";
 import { frameworkBadRequest } from "../../http/Errors/HttpError";
 import { ListQueryError, parseListQuery, type ListQuery, type ListQueryOptions, type ListQueryProblem } from "../../../library/jsonapi";
+import { textOf, type LocalizedText } from "../../../library/workflow";
 import type { WorkflowActor, WorkflowPaging, WorkflowRequest } from "../contracts/types";
 import { WorkflowError } from "../contracts/WorkflowError";
+import { WorkflowLanguages } from "./WorkflowLanguages";
 
 /** Who calls a route: their rights and how they are recorded as an actor. */
 export interface WorkflowCaller {
   readonly access: SubjectAccess;
   readonly actor: WorkflowActor;
   readonly request: WorkflowRequest;
+  /** The language of the request: `Accept-Language` among `workflow.languages`. */
+  readonly language: string;
+}
+
+/** A record with `titleText`: its `title` in the language of the request. `title` itself stays for editing. */
+export function withTitleText<T extends { readonly title: LocalizedText }>(item: T, language: string, fallback: string): T & { readonly titleText: string } {
+  return { ...item, titleText: textOf(item.title, language, fallback) };
+}
+
+/** The default language, for {@link withTitleText}. */
+export function defaultLanguage(ctx: HttpContext): string {
+  return ctx.services.resolve(WorkflowLanguages).default;
 }
 
 /**
@@ -23,7 +37,7 @@ export async function callerOf(ctx: HttpContext, permission?: string, object?: A
   if (permission !== undefined && !await access.can(permission, object)) throw new ForbiddenError();
   const sub = access.subject.sub;
   const [id = sub.slice(sub.lastIndexOf(":") + 1)] = await access.ownerIds();
-  return { access, actor: { kind: "user", id }, request: { ip: ctx.clientIp ?? null, userAgent: ctx.header("user-agent") ?? null } };
+  return { access, actor: { kind: "user", id }, request: { ip: ctx.clientIp ?? null, userAgent: ctx.header("user-agent") ?? null }, language: ctx.services.resolve(WorkflowLanguages).of(ctx.header("accept-language")) };
 }
 
 /** A route parameter as a string. */
@@ -31,6 +45,11 @@ export function param(ctx: HttpContext, name: string): string {
   return String(ctx.params[name] ?? "");
 }
 
+/** A title or a description from a body; the service checks it. */
+export function optionalText(value: unknown): LocalizedText | null | undefined {
+  return value as LocalizedText | null | undefined;
+}
+
 /** The JSON body as an object; anything else is `invalid_input`. */
 export async function body(ctx: HttpContext): Promise<Record<string, unknown>> {
   const text = await ctx.text();

package/core/workflow/runtime_module/WorkflowRuntime.module.ts

@@ -5,10 +5,11 @@ import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinit
 import { runtimePermissions } from "./access/Runtime.permissions";
 import { WorkflowRetention } from "./background/WorkflowRetention";
 import { WorkflowWorker } from "./background/WorkflowWorker";
-import { workflowRuntimeConfig } from "./config/Runtime.config";
 import { EventsController } from "./http/Events.controller";
 import { InstancesController } from "./http/Instances.controller";
+import { ChildCalls } from "./internal/ChildCalls";
 import { GraphCache } from "./internal/GraphCache";
+import { RunLimits } from "./internal/RunLimits";
 import { Schedules } from "./internal/Schedules";
 import { TimerStep } from "./internal/TimerStep";
 import { ToolStep } from "./internal/ToolStep";
@@ -25,7 +26,6 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
 @Module({
   imports: [AccessModule, WorkflowDefinitionsModule],
   permissions: runtimePermissions,
-  config: [workflowRuntimeConfig],
   ormBazis: { context: RuntimeDbContext, entities: [...RUNTIME_ENTITIES], ownedStore: runtimeStore, registerRepositories: false },
   providers: [
     singleton(GraphCache),
@@ -33,6 +33,8 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
     scoped(ToolStep),
     scoped(TimerStep),
     scoped(Schedules),
+    scoped(ChildCalls),
+    scoped(RunLimits),
     singleton(WorkflowInputValidator, DefaultWorkflowInputValidator),
     scoped(IWorkflowRuntime, WorkflowRuntime),
   ],

package/core/workflow/runtime_module/access/Runtime.permissions.ts

@@ -1,24 +1,26 @@
 import { definePermissions } from "../../../access";
+import { ProcessFolderLookup } from "../../definitions_module/access/ProcessFolder.lookup";
 
 const process = { ref: "workflow.process", column: "processKey" };
+const folder = { ref: "workflow.folder", lookup: ProcessFolderLookup };
 
 /** The rights of running processes (WORKFLOW-002 §6.2). */
 export const runtimePermissions = definePermissions({
   "workflow.instances.start": {
     title: { en: "Start processes", ru: "Запускать процессы" },
     scope: "request",
-    on: { process },
+    on: { process, folder },
   },
   "workflow.instances.read": {
     title: { en: "See instances", ru: "Видеть экземпляры" },
     scope: { column: "partition" },
-    on: { process },
+    on: { process, folder },
     owner: "startedById",
   },
   "workflow.instances.manage": {
     title: { en: "Cancel and retry instances", ru: "Отменять и повторять экземпляры" },
     scope: { column: "partition" },
-    on: { process },
+    on: { process, folder },
   },
   "workflow.events.emit": {
     title: { en: "Send events to processes", ru: "Отправлять события процессам" },

package/core/workflow/runtime_module/background/WorkflowRetention.ts

@@ -5,12 +5,12 @@ import { WorkflowClock } from "../../contracts/WorkflowClock";
 import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import { WORKFLOW_INSTANCES_DELETED } from "../events/Runtime.events";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
-import type { WorkflowSettings } from "../config/Runtime.config";
+import type { WorkflowSettings } from "../../contracts/Workflow.config";
 
 const DAY_MS = 86_400_000;
 
 /**
- * Deletes `completed` and `cancelled` instances older than their process's
+ * Deletes `completed`, `cancelled` and `timedOut` instances older than their process's
  * `retentionDays`, with tokens, jobs, subscriptions and history (by cascade),
  * `retention.batchSize` at a time. `failed` instances wait for a person and stay.
  * Each deleted batch is published as `WORKFLOW_INSTANCES_DELETED`, so parts
@@ -52,7 +52,7 @@ export class WorkflowRetention extends BackgroundService {
         for (;;) {
           if (signal?.aborted) return deleted;
           const ids = (await db.instances.asNoTracking()
-            .where((i) => i.processKey.eq(policy.key).and(i.status.in(["completed", "cancelled"])).and(i.endedAt.lt(cutoff)))
+            .where((i) => i.processKey.eq(policy.key).and(i.status.in(["completed", "cancelled", "timedOut"])).and(i.endedAt.lt(cutoff)))
             .orderBy((i) => i.id)
             .take(batchSize)
             .select((i) => ({ id: i.id }))

package/core/workflow/runtime_module/background/WorkflowWorker.ts

@@ -2,14 +2,14 @@ import { BackgroundService, delay } from "../../../background";
 import type { ServiceProvider } from "../../../di";
 import { WorkflowClock } from "../../contracts/WorkflowClock";
 import type { ConfigView } from "../../../kernel";
-import type { WorkflowSettings } from "../config/Runtime.config";
+import type { WorkflowSettings } from "../../contracts/Workflow.config";
 import { WorkflowJobs } from "../internal/WorkflowJobs";
 
 /** How often the scheduled starts are matched against the published versions. */
 const RECONCILE_MS = 60_000;
 
 /**
- * Takes due jobs of `bazis_wf_run_jobs` every `worker.intervalMs`, up to
+ * Takes due jobs of `bazis_wf2_run_jobs` every `worker.intervalMs`, up to
  * `worker.batchSize` at a time ({@link WorkflowJobs}). A full batch is
  * followed by the next one at once.
  */

package/core/workflow/runtime_module/events/Runtime.events.ts

@@ -1,5 +1,5 @@
 import { createEventToken } from "../../../kernel";
-import type { FormSpec } from "../../../../library/workflow";
+import type { FormSpec, LocalizedText } from "../../../../library/workflow";
 import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
 
@@ -10,7 +10,7 @@ export interface WorkflowTaskRequested {
   readonly processKey: string;
   readonly nodeId: string;
   readonly partition: string | null;
-  readonly title: string;
+  readonly title: LocalizedText;
   readonly assignee: { readonly role: string } | { readonly user: string };
   readonly form: FormSpec | null;
   /** When the task is due, from the node's `dueIn`. */
@@ -21,16 +21,16 @@ export interface WorkflowTaskRequested {
 export interface WorkflowTokenClosed {
   readonly instanceId: string;
   readonly tokenId: string;
-  /** `cancelled` — the instance was cancelled; `interrupted` — a boundary timer took over the step. */
-  readonly reason: "cancelled" | "interrupted";
+  /** `cancelled` — the instance was cancelled; `interrupted` — a boundary event or a skipped iteration closed the step; `timedOut` — the run took too long. */
+  readonly reason: "cancelled" | "interrupted" | "timedOut";
 }
 
-/** An instance finished: completed or cancelled. */
+/** An instance finished: completed, cancelled or out of time. */
 export interface WorkflowInstanceFinished {
   readonly instanceId: string;
   readonly processKey: string;
   readonly partition: string | null;
-  readonly status: Extract<InstanceStatus, "completed" | "cancelled">;
+  readonly status: Extract<InstanceStatus, "completed" | "cancelled" | "timedOut">;
 }
 
 /** Retention deleted these finished instances with their tokens and history. */

package/core/workflow/runtime_module/http/Instances.controller.ts

@@ -4,12 +4,16 @@ import { Authorize, Controller, Created, Get, Post, type HttpContext } from "../
 import { buildListDocument } from "../../../../library/jsonapi";
 import { body, callerOf, filterOf, listQuery, optionalString, pagingOfList, param, requiredString } from "../../internal/http";
 import type { InstanceStatus } from "../model/WfInstance.model";
-import { IWorkflowRuntime, type InstanceSummary } from "../services/IWorkflowRuntime.service";
+import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import { IWorkflowRuntime, type InstanceSummary, type StartManyItem } from "../services/IWorkflowRuntime.service";
 
 /** Instances over HTTP (WORKFLOW-001 §4); rights are `workflow.instances.*` (WORKFLOW-002 §6.2). */
 @Controller("workflow/instances")
 export class InstancesController {
-  constructor(private readonly runtime: IWorkflowRuntime) {}
+  constructor(
+    private readonly runtime: IWorkflowRuntime,
+    private readonly definitions: IWorkflowDefinitions,
+  ) {}
 
   @Post()
   @Authorize(can("workflow.instances.start"))
@@ -17,23 +21,35 @@ export class InstancesController {
     const request = await body(ctx);
     const processKey = requiredString(request.processKey, "processKey", 64);
     const partition = optionalString(request.partition, "partition") ?? null;
-    const { actor, request: from } = await callerOf(ctx, "workflow.instances.start", { scope: partition, process: processKey });
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.instances.start", { scope: partition, process: processKey, folder: await this.definitions.folderOf(processKey) });
     const instance = await this.runtime.start(processKey, {
       input: request.input,
       partition,
       businessKey: optionalString(request.businessKey, "businessKey") ?? null,
       actor,
       request: from,
+      language,
     });
     return Created(`${ctx.path}/${instance.id}`, instance);
   }
 
+  /** A start per element, for an action over many records (WORKFLOW-002 §5.1). */
+  @Post("bulk")
+  @Authorize(can("workflow.instances.start"))
+  async startMany(ctx: HttpContext) {
+    const request = await body(ctx);
+    const processKey = requiredString(request.processKey, "processKey", 64);
+    const partition = optionalString(request.partition, "partition") ?? null;
+    const { actor, request: from, language } = await callerOf(ctx, "workflow.instances.start", { scope: partition, process: processKey, folder: await this.definitions.folderOf(processKey) });
+    return { data: await this.runtime.startMany(processKey, { items: request.items as readonly StartManyItem[], partition, actor, request: from, language }) };
+  }
+
   @Get()
   @Authorize(can("workflow.instances.read"))
   async list(ctx: HttpContext) {
     const { access } = await callerOf(ctx);
     const list = listQuery(ctx, {
-      filter: { partition: ["eq"], processKey: ["eq"], status: ["eq"], businessKey: ["eq"], startedById: ["eq"] },
+      filter: { partition: ["eq"], processKey: ["eq"], status: ["eq"], businessKey: ["eq"], startedById: ["eq"], parentInstanceId: ["eq"] },
       sort: ["createdAt", "endedAt", "status", "processKey"],
     });
     const page = await this.runtime.instances({
@@ -44,6 +60,7 @@ export class InstancesController {
       status: filterOf(list, "status") as InstanceStatus | undefined,
       businessKey: filterOf(list, "businessKey"),
       startedById: filterOf(list, "startedById"),
+      parentInstanceId: filterOf(list, "parentInstanceId"),
     });
     return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
   }
@@ -52,7 +69,7 @@ export class InstancesController {
   @Authorize(can("workflow.instances.read"))
   async get(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
-    await callerOf(ctx, "workflow.instances.read", objectOf(instance));
+    await callerOf(ctx, "workflow.instances.read", await this.objectOf(instance));
     return instance;
   }
 
@@ -60,7 +77,7 @@ export class InstancesController {
   @Authorize(can("workflow.instances.read"))
   async history(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
-    await callerOf(ctx, "workflow.instances.read", objectOf(instance));
+    await callerOf(ctx, "workflow.instances.read", await this.objectOf(instance));
     return { data: await this.runtime.history(instance.id) };
   }
 
@@ -69,7 +86,7 @@ export class InstancesController {
   async cancel(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
     const request = await body(ctx);
-    const { actor, request: from } = await callerOf(ctx, "workflow.instances.manage", objectOf(instance));
+    const { actor, request: from } = await callerOf(ctx, "workflow.instances.manage", await this.objectOf(instance));
     return await this.runtime.cancel(instance.id, { reason: optionalString(request.reason, "reason", 1000) ?? null, actor, request: from });
   }
 
@@ -77,14 +94,14 @@ export class InstancesController {
   @Authorize(can("workflow.instances.manage"))
   async retry(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
-    const { actor, request } = await callerOf(ctx, "workflow.instances.manage", objectOf(instance));
+    const { actor, request } = await callerOf(ctx, "workflow.instances.manage", await this.objectOf(instance));
     return await this.runtime.retry(instance.id, { actor, request });
   }
-}
-contextOnlyController(InstancesController);
 
-/** The instance as the object of a permission. */
-function objectOf(instance: InstanceSummary): AccessObject {
-  return { scope: instance.partition, process: instance.processKey, startedById: instance.startedBy.id };
+  /** The instance as the object of a permission. */
+  private async objectOf(instance: InstanceSummary): Promise<AccessObject> {
+    return { scope: instance.partition, process: instance.processKey, folder: await this.definitions.folderOf(instance.processKey), startedById: instance.startedBy.id };
+  }
 }
+contextOnlyController(InstancesController);
 

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

@@ -0,0 +1,186 @@
+import { inputSpecOf, resolveInput } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
+import { WorkflowError } from "../../contracts/WorkflowError";
+import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
+import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfInstance } from "../model/WfInstance.model";
+import type { WfJob } from "../model/WfJob.model";
+import type { WfToken } from "../model/WfToken.model";
+import { dataOf, runActorOf, type StepError, type WorkflowEngine } from "./WorkflowEngine";
+
+/** How deep processes may call each other: a process that calls itself has to stop somewhere. */
+const MAX_DEPTH = 16;
+
+/**
+ * `callProcess`: the jobs between a caller and the process it called. Each runs in
+ * the transaction of one instance, so caller and child never wait for each other.
+ * The child runs on behalf of the caller's actor, in its partition.
+ */
+export class ChildCalls {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+    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,
+  ) {}
+
+  /**
+   * A `call` job: the step starts its process. If it has called already (a retry, a
+   * repeat after a crash), it goes on with that child: a failed one is retried, so
+   * that its finished steps do not run twice. A cancelled or timed out one is called
+   * anew only when the step was entered again (`fresh`).
+   */
+  async call(job: WfJob): Promise<void> {
+    const instance = job.instanceId === null ? undefined : await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(job.instanceId!));
+    const token = job.tokenId === null ? undefined : await this.db.tokens.asNoTracking().firstOrDefault((t) => t.id.eq(job.tokenId!));
+    if (!instance || !token || instance.status !== "running" || token.status !== "waiting") {
+      await this.dropJob(job);
+      return;
+    }
+    const child = await this.lastChild(instance.id, token.id);
+    if (child?.status === "running" || child?.status === "pending") {
+      await this.dropJob(job);
+      return;
+    }
+    if (child?.status === "failed") {
+      const actor = runActorOf((await this.engine.graphOf(instance.versionId)).document, instance);
+      await this.engine.inStep(child.id, async (step) => {
+        await this.dropJob(job);
+        if (step.instance.status === "failed") await this.engine.retry(step, actor);
+      });
+      return;
+    }
+    if (child?.status === "completed") {
+      await this.engine.inStep(instance.id, async (step) => {
+        await this.dropJob(job);
+        await this.engine.complete(step, token.id, child.output ?? {});
+      });
+      return;
+    }
+    if (child && (job.payload as { fresh?: boolean } | null)?.fresh !== true) {
+      await this.applyEnd(job, instance.id, token.id, child);
+      return;
+    }
+    await this.start(job, instance, token);
+  }
+
+  private async start(job: WfJob, instance: WfInstance, token: WfToken): Promise<void> {
+    const graph = await this.engine.graphOf(instance.versionId);
+    const config = graph.document.nodes[token.nodeId]?.config ?? {};
+    const key = String(config.process ?? "");
+    const depth = (typeof instance.trigger?.depth === "number" ? instance.trigger.depth : 0) + 1;
+    const actor = runActorOf(graph.document, instance);
+    const refuse = (error: StepError) => this.engine.inStep(instance.id, async (step) => {
+      await this.dropJob(job);
+      const current = step.tokens.find((t) => t.id === token.id);
+      if (current?.status === "waiting" && step.instance.status === "running") await this.engine.failStep(step, current, error);
+    });
+    if (depth > MAX_DEPTH) {
+      await refuse({ code: "call_depth", message: `Processes call each other deeper than ${MAX_DEPTH} levels` });
+      return;
+    }
+    let version: VersionDetails;
+    try {
+      version = await this.definitions.latest(key);
+    } catch (error) {
+      if (!(error instanceof WorkflowError)) throw error;
+      await refuse({ code: "process_unavailable", message: error.message, reason: error.code });
+      return;
+    }
+    const start = Object.entries(version.document.nodes).find(([, node]) => node.kind === "manualStart");
+    if (!start) {
+      await refuse({ code: "process_unavailable", message: `Process ${key} has no manual start` });
+      return;
+    }
+    const input = resolveInput(config.input ?? {}, dataOf(instance, this.engine.now(), token));
+    const { value, issues } = await this.services.resolve(WorkflowInputValidator).validate(inputSpecOf(version.document), input, { purpose: "input", processKey: key, partition: instance.partition, language: this.languages.default, actor });
+    if (issues.length > 0) {
+      await refuse({ code: "invalid_input", message: `The input of process ${key} is invalid: ${issues.map((issue) => `${issue.field}: ${issue.message}`).join("; ")}` });
+      return;
+    }
+    const childGraph = this.engine.cache(version);
+    await this.engine.inStep(instance.id, async (step) => {
+      await this.dropJob(job);
+      const current = step.tokens.find((t) => t.id === token.id);
+      if (current?.status !== "waiting" || step.instance.status !== "running") return;
+      const { id } = await this.engine.begin(childGraph, start[0], {
+        input: value,
+        partition: step.instance.partition,
+        businessKey: null,
+        startedVia: "callProcess",
+        actor,
+        parent: { instanceId: step.instance.id, tokenId: current.id, depth },
+        cause: { instanceId: step.instance.id, processKey: step.instance.processKey, nodeId: current.nodeId },
+      });
+      this.engine.history(step, current, current.nodeId, "called", { process: key, version: version.version, instanceId: id });
+    });
+  }
+
+  /** A `returned` job: a child stopped. If its caller no longer waits, the job drops; a caller that is itself stopped looks again on its retry. */
+  async returned(job: WfJob): Promise<void> {
+    const { parentInstanceId, parentTokenId } = job.payload as { parentInstanceId: string; parentTokenId: string };
+    const child = job.instanceId === null ? undefined : await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(job.instanceId!));
+    if (!child) {
+      await this.dropJob(job);
+      return;
+    }
+    await this.applyEnd(job, parentInstanceId, parentTokenId, child);
+  }
+
+  private async applyEnd(job: WfJob, instanceId: string, tokenId: string, child: WfInstance): Promise<void> {
+    const done = await this.engine.inStep(instanceId, async (step) => {
+      await this.dropJob(job);
+      const token = step.tokens.find((t) => t.id === tokenId);
+      if (token?.status !== "waiting" || step.instance.status !== "running") return;
+      if (child.status === "completed") {
+        this.engine.history(step, token, token.nodeId, "returned", { instanceId: child.id });
+        await this.engine.complete(step, tokenId, child.output ?? {});
+        return;
+      }
+      const error = errorOf(child);
+      if (error) await this.engine.failStep(step, token, error);
+    });
+    if (done === null) await this.dropJob(job);
+  }
+
+  /** A `cancelChildren` job: the step that called is closed, so is what it called. */
+  async cancelChildren(job: WfJob): Promise<void> {
+    const { tokenId, reason } = job.payload as { tokenId: string; reason: string };
+    const parent = job.instanceId === null ? undefined : await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(job.instanceId!));
+    if (parent) {
+      const children = await this.db.instances.asNoTracking()
+        .where((i) => i.parentInstanceId.eq(parent.id).and(i.parentTokenId.eq(tokenId)).and(i.status.in(["pending", "running", "failed"])))
+        .toList();
+      const actor = { kind: "system" as const, id: `process:${parent.processKey}` };
+      for (const child of children) {
+        await this.engine.inStep(child.id, async (step) => {
+          if (step.instance.status === "pending" || step.instance.status === "running" || step.instance.status === "failed") await this.engine.cancel(step, reason, actor);
+        });
+      }
+    }
+    await this.dropJob(job);
+  }
+
+  /** The newest child of a step. */
+  private async lastChild(instanceId: string, tokenId: string): Promise<WfInstance | undefined> {
+    const children = await this.db.instances.asNoTracking().where((i) => i.parentInstanceId.eq(instanceId).and(i.parentTokenId.eq(tokenId))).orderBy((i) => i.id).toList();
+    return children.at(-1);
+  }
+
+  private async dropJob(job: WfJob): Promise<void> {
+    await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+  }
+}
+
+/** The failure of a step whose child stopped otherwise than by completing; `undefined` while it runs again. */
+function errorOf(child: WfInstance): StepError | undefined {
+  const about = `Instance ${child.id} of process ${child.processKey}`;
+  if (child.status === "failed") return { code: "child_failed", message: `${about} failed: ${child.error?.message ?? ""}`, ...(child.error ? { reason: child.error.code } : {}) };
+  if (child.status === "cancelled") return { code: "child_cancelled", message: `${about} was cancelled` };
+  if (child.status === "timedOut") return { code: "child_timed_out", message: `${about} took too long`, reason: "timeout" };
+  return undefined;
+}

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

@@ -10,6 +10,8 @@ export interface ProcessGraph {
   readonly incoming: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
   /** Boundary nodes by the step they are attached to. */
   readonly boundaries: ReadonlyMap<string, readonly (readonly [string, ProcessNode])[]>;
+  /** The node an iteration begins with, by loop. */
+  readonly entries: ReadonlyMap<string, string>;
 }
 
 export function buildGraph(versionId: string, processKey: string, version: number, document: ProcessDocument): ProcessGraph {
@@ -23,7 +25,11 @@ export function buildGraph(versionId: string, processKey: string, version: numbe
   for (const [id, node] of Object.entries(document.nodes)) {
     if (node.attachedTo !== undefined) boundaries.set(node.attachedTo, [...boundaries.get(node.attachedTo) ?? [], [id, node]]);
   }
-  return { versionId, processKey, version, document, outgoing, incoming, boundaries };
+  const entries = new Map<string, string>();
+  for (const [id, node] of Object.entries(document.nodes)) {
+    if (node.parent !== undefined && node.attachedTo === undefined && !incoming.has(id)) entries.set(node.parent, id);
+  }
+  return { versionId, processKey, version, document, outgoing, incoming, boundaries, entries };
 }
 
 /** Graphs of versions in memory. Versions are immutable, so entries never go stale; the oldest go first past the limit. */