bazis 0.132.0 → 0.134.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/core/agent/AgentToolExecutor.ts +5 -0
  2. package/core/agent/Tool.contract.ts +2 -2
  3. package/core/agent/metadata.ts +11 -0
  4. package/core/infra/connectors/codex/CodexAppServerClient.ts +1 -1
  5. package/core/scripts/di-generate.ts +8 -0
  6. package/core/tools/StandardTools.module.ts +14 -0
  7. package/core/tools/generated/deps.ts +10 -0
  8. package/core/tools/index.ts +8 -0
  9. package/core/tools/orm/OrmEntity.references.ts +71 -0
  10. package/core/tools/orm/ormEntityTools.ts +423 -0
  11. package/core/workflow/contracts/WorkflowError.ts +2 -1
  12. package/core/workflow/contracts/WorkflowPartitions.ts +29 -0
  13. package/core/workflow/contracts/WorkflowProcessUsage.ts +8 -0
  14. package/core/workflow/definitions_module/WorkflowDefinitions.module.ts +7 -2
  15. package/core/workflow/definitions_module/access/Definitions.permissions.ts +4 -2
  16. package/core/workflow/definitions_module/access/ProcessPartition.lookup.ts +27 -0
  17. package/core/workflow/definitions_module/code/CodeProcessPublisher.ts +5 -4
  18. package/core/workflow/definitions_module/events/Definitions.events.ts +1 -1
  19. package/core/workflow/definitions_module/http/Processes.controller.ts +21 -5
  20. package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts +10 -0
  21. package/core/workflow/definitions_module/services/WorkflowDefinitions.service.ts +28 -2
  22. package/core/workflow/generated/deps.ts +12 -2
  23. package/core/workflow/index.ts +5 -0
  24. package/core/workflow/runtime_module/WorkflowRuntime.module.ts +9 -0
  25. package/core/workflow/runtime_module/background/WorkflowRetention.ts +2 -2
  26. package/core/workflow/runtime_module/events/Runtime.events.ts +4 -4
  27. package/core/workflow/runtime_module/http/Instances.controller.ts +14 -2
  28. package/core/workflow/runtime_module/internal/ChildCalls.ts +186 -0
  29. package/core/workflow/runtime_module/internal/EventDelivery.ts +234 -0
  30. package/core/workflow/runtime_module/internal/GraphCache.ts +7 -1
  31. package/core/workflow/runtime_module/internal/RunLimits.ts +134 -0
  32. package/core/workflow/runtime_module/internal/RuntimeProcessUsage.ts +13 -0
  33. package/core/workflow/runtime_module/internal/Schedules.ts +97 -30
  34. package/core/workflow/runtime_module/internal/TimerStep.ts +11 -1
  35. package/core/workflow/runtime_module/internal/ToolStep.ts +4 -4
  36. package/core/workflow/runtime_module/internal/WorkflowEngine.ts +544 -132
  37. package/core/workflow/runtime_module/internal/WorkflowJobs.ts +44 -6
  38. package/core/workflow/runtime_module/model/WfHistory.model.ts +1 -1
  39. package/core/workflow/runtime_module/model/WfInstance.model.ts +7 -4
  40. package/core/workflow/runtime_module/model/WfJob.model.ts +18 -8
  41. package/core/workflow/runtime_module/model/WfToken.model.ts +5 -3
  42. package/core/workflow/runtime_module/services/IWorkflowRuntime.service.ts +59 -4
  43. package/core/workflow/runtime_module/services/WorkflowRuntime.service.ts +72 -42
  44. package/core/workflow/tasks_module/events/TaskEvents.ts +4 -8
  45. package/core/workflow/tasks_module/services/WorkflowTasks.service.ts +1 -1
  46. package/library/workflow/ProcessDocument.ts +14 -0
  47. package/library/workflow/cron.ts +103 -24
  48. package/library/workflow/expressions.ts +5 -1
  49. package/library/workflow/index.ts +2 -2
  50. package/library/workflow/masking.ts +17 -3
  51. package/library/workflow/mermaid.ts +22 -6
  52. package/library/workflow/nodeKinds.ts +123 -9
  53. package/library/workflow/palette.ts +3 -1
  54. package/library/workflow/paths.ts +10 -4
  55. package/library/workflow/structure.ts +33 -4
  56. package/library/workflow/validateProcess.ts +141 -17
  57. package/package.json +2 -1
@@ -1,5 +1,5 @@
1
1
  import type { EventToken } from "../../../kernel";
2
- import { durationMs, evaluateExpression, initialVarsOf, isTruthy, masksPersonal, maskByMapping, nodeKindOf, outputOf, personalPaths, personalVariables, PERSONAL_MASK, readPath, type Expr, type FormSpec, type InstanceData, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
2
+ import { durationMs, evaluateExpression, initialVarsOf, isTruthy, masksPersonal, maskByMapping, nodeKindOf, outputOf, personalPaths, personalVariables, PERSONAL_MASK, readPath, type Expr, type FormSpec, type InstanceData, type ProcessDocument, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
3
3
  import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
4
4
  import type { WorkflowClock } from "../../contracts/WorkflowClock";
5
5
  import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
@@ -8,7 +8,7 @@ import { WORKFLOW_INSTANCE_CANCELLED, WORKFLOW_INSTANCE_FINISHED, WORKFLOW_INSTA
8
8
  import type { RuntimeDbContext } from "../model/Runtime.dbContext";
9
9
  import { WfHistory, type HistoryType } from "../model/WfHistory.model";
10
10
  import { WfInstance, type StartedVia } from "../model/WfInstance.model";
11
- import { WfJob } from "../model/WfJob.model";
11
+ import { WfJob, type JobKind } from "../model/WfJob.model";
12
12
  import { WfSubscription } from "../model/WfSubscription.model";
13
13
  import { WfToken } from "../model/WfToken.model";
14
14
  import { buildGraph, type GraphCache, type ProcessGraph } from "./GraphCache";
@@ -28,6 +28,11 @@ export interface Step {
28
28
  readonly tokens: WfToken[];
29
29
  readonly graph: ProcessGraph;
30
30
  readonly events: PendingEvent[];
31
+ /** Iterations of loops this step has begun: past {@link LOOP_BATCH} the rest go to a job. */
32
+ iterations: number;
33
+ /** Rows for the end of the step ({@link WorkflowEngine.flush}). */
34
+ jobs: WfJob[];
35
+ readonly subscriptions: WfSubscription[];
31
36
  }
32
37
 
33
38
  export interface BeginOptions {
@@ -40,10 +45,81 @@ export interface BeginOptions {
40
45
  readonly request?: WorkflowRequest | null;
41
46
  /** The event that starts it: `$event` and `$trigger.eventKey`. */
42
47
  readonly event?: { readonly key: string; readonly payload: unknown };
48
+ /** The step of the instance that called it. */
49
+ readonly parent?: { readonly instanceId: string; readonly tokenId: string; readonly depth: number };
50
+ /** What led to the start: `$trigger.cause`. */
51
+ readonly cause?: Readonly<Record<string, unknown>>;
52
+ /** It waits as `pending` whatever the limits say: `overlap: "queue"`. */
53
+ readonly queued?: boolean;
54
+ /** The firing a scheduled start belongs to: `$trigger.scheduledAt`. */
55
+ readonly scheduledAt?: Date;
43
56
  }
44
57
 
58
+ /** Why a step failed. `reason` is the business reason an error boundary may name. */
59
+ export interface StepError {
60
+ readonly code: string;
61
+ readonly message: string;
62
+ readonly reason?: string;
63
+ }
64
+
65
+ /** The result of {@link WorkflowEngine.begin}: the new instance, or with `skipped` the unfinished one that took its place (`sameKey: "skip"`). */
66
+ export interface Begun {
67
+ readonly id: string;
68
+ readonly skipped: boolean;
69
+ }
70
+
71
+ /** What a token inside a loop body sees besides the instance: its element and what steps of the iteration gave. */
72
+ interface Locals {
73
+ readonly item: unknown;
74
+ readonly index: number;
75
+ readonly vars: Readonly<Record<string, unknown>>;
76
+ readonly nodes: Readonly<Record<string, unknown>>;
77
+ }
78
+
79
+ /** The progress of a running loop, in the `output` of its token. `items` is taken once: the body may change the list it came from. */
80
+ interface LoopState {
81
+ readonly items: readonly unknown[] | null;
82
+ readonly next: number;
83
+ readonly skipped: number;
84
+ readonly collected: Readonly<Record<string, unknown>>;
85
+ /** The rest waits for a `loop` job. */
86
+ readonly yielded: boolean;
87
+ }
88
+
89
+ interface LoopConfig {
90
+ readonly over?: Expr;
91
+ readonly while?: Expr;
92
+ readonly times?: number;
93
+ readonly item?: string;
94
+ readonly index?: string;
95
+ readonly maxIterations: number;
96
+ readonly parallel?: { readonly limit: number };
97
+ readonly onItemError?: "stop" | "skip";
98
+ readonly collect?: { readonly from: Expr; readonly to: string };
99
+ }
100
+
101
+ /** Where a token runs: the loop and the iteration. Top-level tokens have neither. */
102
+ type Frame = Pick<WfToken, "parentTokenId" | "iteration" | "locals">;
103
+
104
+ const TOP: Frame = { parentTokenId: null, iteration: null, locals: null };
105
+
45
106
  const LIVE = new Set(["active", "waiting", "failed"]);
46
107
 
108
+ /** How many iterations one transaction begins: a body without waits must not hold the instance for ten thousand of them. */
109
+ const LOOP_BATCH = 100;
110
+
111
+ /** Jobs that end with the instance. The others carry news of its end to someone else. */
112
+ const OWN_JOBS: readonly JobKind[] = ["tool", "timer", "loop", "call", "runTimeout"];
113
+
114
+ /** Whether two tokens are in one iteration: tokens of other iterations pass the same nodes and do not touch each other. */
115
+ function sameFrame(a: Frame, b: Frame): boolean {
116
+ return a.parentTokenId === b.parentTokenId && a.iteration === b.iteration;
117
+ }
118
+
119
+ function localsOf(token: Frame): Locals | null {
120
+ return token.locals as unknown as Locals | null;
121
+ }
122
+
47
123
  /**
48
124
  * Moves tokens along the graph up to the steps that wait (a Tool, a task, a
49
125
  * join) and finishes the instance when no live token is left. No state lives in
@@ -79,10 +155,102 @@ export class WorkflowEngine {
79
155
  return graph;
80
156
  }
81
157
 
82
- /** Creates an instance of `graph` and moves its token from `startNodeId`. */
83
- async begin(graph: ProcessGraph, startNodeId: string, options: BeginOptions): Promise<string> {
84
- const instance = Object.assign(new WfInstance(), {
158
+ /**
159
+ * Creates an instance of `graph` and moves its token from `startNodeId`, or
160
+ * leaves it `pending` when `maxConcurrent` or `sameKey` tell it to wait. With
161
+ * `sameKey: "skip"` no instance is created.
162
+ */
163
+ async begin(graph: ProcessGraph, startNodeId: string, options: BeginOptions): Promise<Begun> {
164
+ return await this.db.transactionScope(async (transaction) => {
165
+ const admission = await this.admit(graph, options.businessKey);
166
+ if (typeof admission === "object") return { id: admission.skippedBy, skipped: true };
167
+ const waits = admission === "queue" || options.queued === true;
168
+ const instance = this.newInstance(graph, options, waits ? "pending" : "running");
169
+ this.db.instances.add(instance);
170
+ await this.db.saveChanges();
171
+ const step = this.stepOf(instance, [], graph);
172
+ this.history(step, null, null, "started", { via: options.startedVia }, options.actor);
173
+ step.events.push({
174
+ event: WORKFLOW_INSTANCE_STARTED as EventToken<unknown>,
175
+ payload: { instanceId: instance.id, processKey: graph.processKey, version: graph.version, partition: options.partition, businessKey: options.businessKey, startedVia: options.startedVia, actor: options.actor, request: options.request ?? null },
176
+ });
177
+ const first = this.spawn(step, startNodeId, null, TOP);
178
+ if (waits) {
179
+ first.status = "waiting";
180
+ this.history(step, first, startNodeId, "queued", null);
181
+ } else {
182
+ this.armRun(step);
183
+ await this.advance(step, [first]);
184
+ }
185
+ await this.flush(step);
186
+ this.publishAfter(transaction, step);
187
+ return { id: instance.id, skipped: false };
188
+ });
189
+ }
190
+
191
+ private stepOf(instance: WfInstance, tokens: WfToken[], graph: ProcessGraph): Step {
192
+ return { instance, tokens, graph, events: [], iterations: 0, jobs: [], subscriptions: [] };
193
+ }
194
+
195
+ /**
196
+ * Saves the step. Jobs and subscriptions are inserted past the change tracker:
197
+ * they belong to the worker, and one scope may delete such rows directly in its
198
+ * next step, which an ORM context that holds them would refuse.
199
+ */
200
+ private async flush(step: Step): Promise<void> {
201
+ await this.db.saveChanges();
202
+ for (const job of step.jobs) await this.db.jobs.insertIfAbsent(job, { conflictBy: (j) => [j.id] });
203
+ for (const subscription of step.subscriptions) await this.db.subscriptions.insertIfAbsent(subscription, { conflictBy: (s) => [s.id] });
204
+ }
205
+
206
+ /** Whether a start goes ahead, under the lock of the process: only processes with a limit take it. */
207
+ private async admit(graph: ProcessGraph, businessKey: string | null): Promise<"start" | "queue" | { readonly skippedBy: string }> {
208
+ const { maxConcurrent, sameKey = "allow" } = graph.document.settings ?? {};
209
+ const keyed = sameKey !== "allow" && businessKey !== null;
210
+ if (maxConcurrent === undefined && !keyed) return "start";
211
+ await this.lockProcess(graph.processKey);
212
+ if (keyed) {
213
+ const same = await this.db.instances.asNoTracking()
214
+ .where((i) => i.processKey.eq(graph.processKey).and(i.businessKey.eq(businessKey)).and(i.status.in(["pending", "running", "failed"])))
215
+ .firstOrDefault();
216
+ if (same) return sameKey === "skip" ? { skippedBy: same.id } : "queue";
217
+ }
218
+ return maxConcurrent !== undefined && await this.runningOf(graph.processKey) >= maxConcurrent ? "queue" : "start";
219
+ }
220
+
221
+ /** One transaction at a time decides who of a process runs. Held until the commit. */
222
+ async lockProcess(processKey: string): Promise<void> {
223
+ await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext({0}))", `bazis.workflow.process:${processKey}`);
224
+ }
225
+
226
+ async runningOf(processKey: string): Promise<number> {
227
+ return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.status.eq("running"))).count();
228
+ }
229
+
230
+ /** Scheduled runs of a process that still go on in a partition, for `overlap`. A failed one waits for a person and takes no place. */
231
+ async scheduledLive(processKey: string, partition: string | null): Promise<number> {
232
+ return await this.db.instances.asNoTracking()
233
+ .where((i) => i.processKey.eq(processKey).and(i.startedVia.eq("schedule")).and(i.status.in(["pending", "running"])).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)))
234
+ .count();
235
+ }
236
+
237
+ /** A `pending` instance got its place: its token moves from the start. */
238
+ async release(step: Step): Promise<void> {
239
+ if (step.instance.status !== "pending") return;
240
+ step.instance.status = "running";
241
+ const first = step.tokens.filter((t) => t.status === "waiting");
242
+ for (const token of first) {
243
+ token.status = "active";
244
+ this.history(step, token, token.nodeId, "released", null);
245
+ }
246
+ this.armRun(step);
247
+ await this.advance(step, first);
248
+ }
249
+
250
+ private newInstance(graph: ProcessGraph, options: BeginOptions, status: "pending" | "running"): WfInstance {
251
+ return Object.assign(new WfInstance(), {
85
252
  id: Bun.randomUUIDv7(),
253
+ status,
86
254
  versionId: graph.versionId,
87
255
  processKey: graph.processKey,
88
256
  version: graph.version,
@@ -95,26 +263,29 @@ export class WorkflowEngine {
95
263
  at: this.now().toISOString(),
96
264
  actor: options.actor,
97
265
  ...(options.event === undefined ? {} : { eventKey: options.event.key }),
266
+ ...(options.cause === undefined ? {} : { cause: options.cause }),
267
+ ...(options.parent === undefined ? {} : { depth: options.parent.depth }),
268
+ ...(options.scheduledAt === undefined ? {} : { scheduledAt: options.scheduledAt.toISOString() }),
98
269
  },
99
270
  businessKey: options.businessKey,
100
271
  startedVia: options.startedVia,
101
272
  startedByKind: options.actor.kind,
102
273
  startedById: options.actor.id,
274
+ parentInstanceId: options.parent?.instanceId ?? null,
275
+ parentTokenId: options.parent?.tokenId ?? null,
103
276
  });
104
- await this.db.transactionScope(async (transaction) => {
105
- this.db.instances.add(instance);
106
- await this.db.saveChanges();
107
- const step: Step = { instance, tokens: [], graph, events: [] };
108
- this.history(step, null, null, "started", { via: options.startedVia }, options.actor);
109
- step.events.push({
110
- event: WORKFLOW_INSTANCE_STARTED as EventToken<unknown>,
111
- payload: { instanceId: instance.id, processKey: graph.processKey, version: graph.version, partition: options.partition, businessKey: options.businessKey, startedVia: options.startedVia, actor: options.actor, request: options.request ?? null },
112
- });
113
- await this.advance(step, [this.spawn(step, startNodeId, null)]);
114
- await this.db.saveChanges();
115
- this.publishAfter(transaction, step);
116
- });
117
- return instance.id;
277
+ }
278
+
279
+ /** A run with `runTimeout` has a job that ends it. */
280
+ private armRun(step: Step, startedAt = this.now()): void {
281
+ const timeout = step.graph.document.settings?.runTimeout;
282
+ const ms = timeout === undefined ? undefined : durationMs(timeout);
283
+ if (ms === undefined) return;
284
+ this.addJob(step, "runTimeout", { dueAt: new Date(Math.max(startedAt.getTime() + ms, this.now().getTime())) });
285
+ }
286
+
287
+ private addJob(step: Step, kind: JobKind, fields: Partial<Pick<WfJob, "tokenId" | "dueAt" | "payload">> = {}): void {
288
+ step.jobs.push(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind, instanceId: step.instance.id, dueAt: this.now(), createdAt: this.now(), ...fields }));
118
289
  }
119
290
 
120
291
  /**
@@ -130,9 +301,9 @@ export class WorkflowEngine {
130
301
  const instance = await this.db.instances.where((i) => i.id.eq(instanceId)).forUpdate().firstOrDefault();
131
302
  if (!instance) return null;
132
303
  const tokens = await this.db.tokens.where((t) => t.instanceId.eq(instanceId).and(t.status.in(["active", "waiting", "failed"]))).toList();
133
- const step: Step = { instance, tokens, graph, events: [] };
304
+ const step = this.stepOf(instance, tokens, graph);
134
305
  const result = await work(step);
135
- await this.db.saveChanges();
306
+ await this.flush(step);
136
307
  this.publishAfter(transaction, step);
137
308
  return result;
138
309
  });
@@ -146,45 +317,100 @@ export class WorkflowEngine {
146
317
  async complete(step: Step, tokenId: string, output: unknown, actor?: WorkflowActor): Promise<boolean> {
147
318
  const token = step.tokens.find((t) => t.id === tokenId);
148
319
  if (!token || token.status !== "waiting" || step.instance.status !== "running") return false;
320
+ if (actor !== undefined) this.history(step, token, token.nodeId, "completed", null, actor);
321
+ await this.advance(step, this.finish(step, token, output));
322
+ return true;
323
+ }
324
+
325
+ /** A step's result goes to `$nodes.<node>` and to `saveTo`; the token leaves. */
326
+ private finish(step: Step, token: WfToken, output: unknown): WfToken[] {
149
327
  const node = step.graph.document.nodes[token.nodeId]!;
150
328
  token.output = output ?? null;
151
- step.instance.nodes = { ...step.instance.nodes, [token.nodeId]: output ?? null };
329
+ this.record(step, token, token.nodeId, output ?? null);
152
330
  const saveTo = node.config?.saveTo;
153
- if (typeof saveTo === "string") step.instance.vars = { ...step.instance.vars, [saveTo]: output ?? null };
154
- if (actor !== undefined) this.history(step, token, token.nodeId, "completed", null, actor);
155
- this.disarm(step, token.nodeId);
156
- await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
157
- return true;
331
+ if (typeof saveTo === "string") this.save(step, token, saveTo, output ?? null);
332
+ this.disarm(step, token);
333
+ return this.leave(step, token, this.single(step, token.nodeId));
334
+ }
335
+
336
+ /** `$nodes.<node>`: inside a loop body it belongs to the iteration. */
337
+ private record(step: Step, token: WfToken, nodeId: string, output: unknown): void {
338
+ const locals = localsOf(token);
339
+ if (locals === null) step.instance.nodes = { ...step.instance.nodes, [nodeId]: output };
340
+ else token.locals = { ...locals, nodes: { ...locals.nodes, [nodeId]: output } };
341
+ }
342
+
343
+ /** `saveTo`: inside a loop body it belongs to the iteration, unless the process declares the variable. */
344
+ private save(step: Step, token: WfToken, name: string, value: unknown): void {
345
+ const locals = localsOf(token);
346
+ if (locals === null || step.graph.document.variables?.some((variable) => variable.name === name)) step.instance.vars = { ...step.instance.vars, [name]: value };
347
+ else token.locals = { ...locals, vars: { ...locals.vars, [name]: value } };
158
348
  }
159
349
 
160
350
  /**
161
- * A step's Tool failed for good. An error boundary attached to the step takes
162
- * the token (first one whose `errorCode` equals the Tool's `reason` or error
163
- * code, else one without `errorCode`); otherwise `onError: "skip"` moves on with
164
- * `{ skipped: true, error }`; otherwise the instance fails.
351
+ * A step failed for good: its Tool, or the process it called. An error boundary
352
+ * attached to the step takes the token (first one whose `errorCode` equals the
353
+ * `reason` or the error code, else one without `errorCode`); otherwise
354
+ * `onError: "skip"` moves on with `{ skipped: true, error }`; otherwise it goes
355
+ * to the loops around the step and then to the whole instance ({@link failed}).
165
356
  */
166
- async failStep(step: Step, token: WfToken, error: { readonly code: string; readonly message: string; readonly reason?: string }): Promise<void> {
167
- const boundaries = (step.graph.boundaries.get(token.nodeId) ?? []).filter(([, node]) => node.kind === "boundaryError");
168
- const matching = boundaries.find(([, node]) => node.config?.errorCode !== undefined && (node.config.errorCode === error.reason || node.config.errorCode === error.code))
169
- ?? boundaries.find(([, node]) => node.config?.errorCode === undefined);
170
- if (!matching) {
171
- if (step.graph.document.nodes[token.nodeId]?.config?.onError === "skip") {
172
- const skipped = { code: error.code, message: error.message, ...(error.reason === undefined ? {} : { reason: error.reason }) };
173
- this.history(step, token, token.nodeId, "skipped", skipped);
174
- await this.complete(step, token.id, { skipped: true, error: skipped });
175
- return;
176
- }
177
- this.fail(step, token, error.code, error.message);
357
+ async failStep(step: Step, token: WfToken, error: StepError): Promise<void> {
358
+ const boundary = this.errorBoundary(step, token.nodeId, error);
359
+ if (boundary) {
360
+ await this.advance(step, this.caught(step, token, boundary, error));
178
361
  return;
179
362
  }
180
- const [boundaryId] = matching;
181
- const caught = { code: error.code, message: error.message, ...(error.reason === undefined ? {} : { reason: error.reason }) };
182
- token.output = { error: caught };
363
+ const node = step.graph.document.nodes[token.nodeId];
364
+ if (node?.config?.onError === "skip") {
365
+ const skipped = detailsOf(error);
366
+ this.history(step, token, token.nodeId, "skipped", skipped);
367
+ if (node.kind === "callProcess") this.addJob(step, "cancelChildren", { payload: { tokenId: token.id, reason: "the caller skipped this step" } });
368
+ await this.complete(step, token.id, { skipped: true, error: skipped });
369
+ return;
370
+ }
371
+ await this.advance(step, this.failed(step, token, error));
372
+ }
373
+
374
+ private errorBoundary(step: Step, nodeId: string, error: StepError): readonly [string, ProcessNode] | undefined {
375
+ const boundaries = (step.graph.boundaries.get(nodeId) ?? []).filter(([, node]) => node.kind === "boundaryError");
376
+ return boundaries.find(([, node]) => node.config?.errorCode !== undefined && (node.config.errorCode === error.reason || node.config.errorCode === error.code))
377
+ ?? boundaries.find(([, node]) => node.config?.errorCode === undefined);
378
+ }
379
+
380
+ /** An error boundary takes over from a step: what ran inside the step closes, the boundary leads on. */
381
+ private caught(step: Step, token: WfToken, [boundaryId]: readonly [string, ProcessNode], error: StepError): WfToken[] {
382
+ const details = detailsOf(error);
383
+ for (const child of this.childrenOf(step, token)) this.closeTree(step, child, "interrupted");
384
+ if (step.graph.document.nodes[token.nodeId]?.kind === "callProcess") this.addJob(step, "cancelChildren", { payload: { tokenId: token.id, reason: "the caller took over the error" } });
385
+ token.output = { error: details };
183
386
  this.close(token, "done");
184
- this.disarm(step, token.nodeId);
185
- this.history(step, token, token.nodeId, "error", { ...caught, boundary: boundaryId });
186
- step.instance.nodes = { ...step.instance.nodes, [boundaryId]: caught };
187
- await this.advance(step, [this.spawn(step, boundaryId, null)]);
387
+ this.disarm(step, token);
388
+ this.history(step, token, token.nodeId, "error", { ...details, boundary: boundaryId });
389
+ this.record(step, token, boundaryId, details);
390
+ return [this.spawn(step, boundaryId, null, token)];
391
+ }
392
+
393
+ /**
394
+ * A failure no step took: the loops around it have their say, from the inside
395
+ * out (`onItemError: "skip"` drops the iteration, an error boundary on the loop
396
+ * takes over). Otherwise the token waits for a retry and the instance is `failed`.
397
+ */
398
+ private failed(step: Step, token: WfToken, error: StepError): WfToken[] {
399
+ for (let inner = token; inner.parentTokenId !== null;) {
400
+ const loop = step.tokens.find((t) => t.id === inner.parentTokenId);
401
+ if (!loop) break;
402
+ if (step.graph.document.nodes[loop.nodeId]?.config?.onItemError === "skip") return this.skipIteration(step, loop, inner.iteration!, error);
403
+ const boundary = this.errorBoundary(step, loop.nodeId, error);
404
+ if (boundary) return this.caught(step, loop, boundary, error);
405
+ inner = loop;
406
+ }
407
+ this.disarm(step, token);
408
+ token.status = "failed";
409
+ step.instance.status = "failed";
410
+ step.instance.error = { node: token.nodeId, code: error.code, message: error.message };
411
+ this.history(step, token, token.nodeId, "error", { code: error.code, message: error.message });
412
+ this.stopped(step);
413
+ return [];
188
414
  }
189
415
 
190
416
  /**
@@ -205,6 +431,14 @@ export class WorkflowEngine {
205
431
  return await this.fireBoundary(step, token, node, { firedAt }, "timer");
206
432
  }
207
433
 
434
+ /** Whether the step takes this event: `eventWait.until` may leave it waiting for the next one. */
435
+ eventAccepted(step: Step, tokenId: string, payload: Record<string, unknown>): boolean {
436
+ const token = step.tokens.find((t) => t.id === tokenId);
437
+ const node = token === undefined ? undefined : step.graph.document.nodes[token.nodeId];
438
+ if (token === undefined || node?.kind !== "eventWait" || node.config?.until === undefined || token.status !== "waiting") return true;
439
+ return isTruthy(evaluateExpression(node.config.until as Expr, { ...dataOf(step.instance, this.now(), token), event: payload }));
440
+ }
441
+
208
442
  /**
209
443
  * An event the token waits for arrived. An `eventWait` step moves on with
210
444
  * the payload (and `saveTo`); a `boundaryEvent` takes its flow like a
@@ -229,66 +463,122 @@ export class WorkflowEngine {
229
463
  const interrupting = node.config?.interrupting !== false;
230
464
  this.history(step, token, token.nodeId, type, { ...details, ...(type === "timer" ? output : {}), interrupting });
231
465
  if (interrupting) {
232
- for (const host of step.tokens.filter((t) => t.nodeId === node.attachedTo && LIVE.has(t.status))) {
233
- this.close(host, "cancelled");
234
- if (step.graph.document.nodes[host.nodeId]?.kind === "userTask") {
235
- step.events.push({ event: WORKFLOW_TOKEN_CLOSED as EventToken<unknown>, payload: { instanceId: step.instance.id, tokenId: host.id, reason: "interrupted" } });
236
- }
237
- }
238
- this.disarm(step, node.attachedTo, token.id);
466
+ for (const host of step.tokens.filter((t) => t.nodeId === node.attachedTo && LIVE.has(t.status) && sameFrame(t, token))) this.closeTree(step, host, "interrupted");
467
+ this.disarm(step, token, token.id, node.attachedTo);
239
468
  }
240
- step.instance.nodes = { ...step.instance.nodes, [token.nodeId]: output };
469
+ this.record(step, token, token.nodeId, output);
241
470
  await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
242
471
  return true;
243
472
  }
244
473
 
245
- /** A step failed: the token waits for a retry, the instance is `failed` with the reason. */
246
- fail(step: Step, token: WfToken, code: string, message: string): void {
247
- this.disarm(step, token.nodeId);
248
- token.status = "failed";
249
- step.instance.status = "failed";
250
- step.instance.error = { node: token.nodeId, code, message };
251
- this.history(step, token, token.nodeId, "error", { code, message });
474
+ /** A step failed outside its Tool: as {@link failStep} without the step's own handlers. */
475
+ async fail(step: Step, token: WfToken, code: string, message: string): Promise<void> {
476
+ await this.advance(step, this.failed(step, token, { code, message }));
252
477
  }
253
478
 
254
- /** Retries the failed steps: their tokens are back on their nodes and the instance runs again. */
479
+ /**
480
+ * Retries the failed steps: their tokens are back on their nodes and the instance
481
+ * runs again. What the failure left behind goes on too: tokens that had not moved,
482
+ * and the jobs a worker dropped while the instance was stopped.
483
+ */
255
484
  async retry(step: Step, actor: WorkflowActor, request: WorkflowRequest | null = null): Promise<void> {
256
485
  const failed = step.tokens.filter((t) => t.status === "failed");
486
+ const left = step.tokens.filter((t) => t.status === "active");
257
487
  step.events.push({
258
488
  event: WORKFLOW_INSTANCE_RETRIED as EventToken<unknown>,
259
489
  payload: { instanceId: step.instance.id, processKey: step.instance.processKey, partition: step.instance.partition, actor, request },
260
490
  });
261
491
  step.instance.status = "running";
262
492
  step.instance.error = null;
493
+ await this.rearm(step);
263
494
  for (const token of failed) {
264
495
  token.status = "active";
265
496
  this.history(step, token, token.nodeId, "retried", null, actor);
266
497
  }
267
- await this.advance(step, failed);
498
+ await this.advance(step, [...failed, ...left]);
499
+ }
500
+
501
+ private async rearm(step: Step): Promise<void> {
502
+ const jobs = await this.db.jobs.asNoTracking().where((j) => j.instanceId.eq(step.instance.id)).toList();
503
+ const held = new Set(jobs.map((job) => job.tokenId));
504
+ for (const token of step.tokens) {
505
+ if (token.status !== "waiting" || held.has(token.id)) continue;
506
+ const kind = step.graph.document.nodes[token.nodeId]?.kind;
507
+ if (kind === "serviceTask") this.addJob(step, "tool", { tokenId: token.id });
508
+ else if (kind === "timerCatch" || kind === "boundaryTimer") this.addJob(step, "timer", { tokenId: token.id });
509
+ else if (kind === "callProcess") this.addJob(step, "call", { tokenId: token.id });
510
+ else if (kind === "loop" && (token.output as LoopState | null)?.yielded === true) this.addJob(step, "loop", { tokenId: token.id });
511
+ }
512
+ if (!jobs.some((job) => job.kind === "runTimeout")) this.armRun(step, new Date(String(step.instance.trigger?.at)));
268
513
  }
269
514
 
270
515
  /** Closes every live token, job and subscription; the application drops the tasks on `WORKFLOW_TOKEN_CLOSED`. */
271
516
  async cancel(step: Step, reason: string | null, actor: WorkflowActor, request: WorkflowRequest | null = null): Promise<void> {
272
- const open = step.tokens.filter((t) => LIVE.has(t.status));
273
517
  step.events.push({
274
518
  event: WORKFLOW_INSTANCE_CANCELLED as EventToken<unknown>,
275
519
  payload: { instanceId: step.instance.id, processKey: step.instance.processKey, partition: step.instance.partition, reason, actor, request },
276
520
  });
277
- for (const token of open) {
278
- token.status = "cancelled";
279
- token.endedAt = this.now();
280
- }
281
- await this.db.jobs.asNoTracking().where((j) => j.instanceId.eq(step.instance.id)).executeDelete();
282
- await this.db.subscriptions.asNoTracking().where((s) => s.instanceId.eq(step.instance.id)).executeDelete();
521
+ await this.closeAll(step, "cancelled");
283
522
  step.instance.status = "cancelled";
284
523
  step.instance.endedAt = this.now();
285
524
  this.history(step, null, null, "cancelled", { reason }, actor);
286
- for (const token of open) {
287
- if (token.nodeId !== "" && step.graph.document.nodes[token.nodeId]?.kind === "userTask") {
288
- step.events.push({ event: WORKFLOW_TOKEN_CLOSED as EventToken<unknown>, payload: { instanceId: step.instance.id, tokenId: token.id, reason: "cancelled" } });
289
- }
290
- }
291
525
  this.finished(step, "cancelled");
526
+ this.stopped(step);
527
+ }
528
+
529
+ /** `runTimeout` passed: the run ends here, whatever it was waiting for. */
530
+ async timeOut(step: Step): Promise<void> {
531
+ const timeout = step.graph.document.settings?.runTimeout ?? "";
532
+ await this.closeAll(step, "timedOut");
533
+ step.instance.status = "timedOut";
534
+ step.instance.endedAt = this.now();
535
+ step.instance.error = { node: "", code: "run_timeout", message: `The run took longer than ${timeout}` };
536
+ this.history(step, null, null, "timedOut", { timeout });
537
+ this.finished(step, "timedOut");
538
+ this.stopped(step);
539
+ }
540
+
541
+ private async closeAll(step: Step, reason: "cancelled" | "timedOut"): Promise<void> {
542
+ for (const token of step.tokens.filter((t) => t.parentTokenId === null || !step.tokens.some((other) => other.id === t.parentTokenId))) {
543
+ if (LIVE.has(token.status)) this.closeTree(step, token, reason);
544
+ }
545
+ await this.dropJobs(step, OWN_JOBS);
546
+ await this.db.subscriptions.asNoTracking().where((s) => s.instanceId.eq(step.instance.id)).executeDelete();
547
+ }
548
+
549
+ /** Removes jobs of these kinds, saved and about to be. */
550
+ private async dropJobs(step: Step, kinds: readonly JobKind[]): Promise<void> {
551
+ step.jobs = step.jobs.filter((job) => !kinds.includes(job.kind));
552
+ await this.db.jobs.asNoTracking().where((j) => j.instanceId.eq(step.instance.id).and(j.kind.in([...kinds]))).executeDelete();
553
+ }
554
+
555
+ /** The live tokens of a loop's body. */
556
+ private childrenOf(step: Step, token: WfToken): WfToken[] {
557
+ return step.tokens.filter((t) => t.parentTokenId === token.id && LIVE.has(t.status));
558
+ }
559
+
560
+ /** Closes a token with all that runs inside it: the body of a loop, a user task, a called process. */
561
+ private closeTree(step: Step, token: WfToken, reason: "cancelled" | "interrupted" | "timedOut"): void {
562
+ for (const child of this.childrenOf(step, token)) this.closeTree(step, child, reason);
563
+ this.close(token, "cancelled");
564
+ const kind = step.graph.document.nodes[token.nodeId]?.kind;
565
+ if (kind === "userTask") step.events.push({ event: WORKFLOW_TOKEN_CLOSED as EventToken<unknown>, payload: { instanceId: step.instance.id, tokenId: token.id, reason } });
566
+ if (kind === "callProcess") this.addJob(step, "cancelChildren", { payload: { tokenId: token.id, reason: `the caller was ${reason}` } });
567
+ }
568
+
569
+ /**
570
+ * The instance stopped running: who waits for it hears of it. Each goes through a
571
+ * job of this instance, so that its transaction never holds another instance's row.
572
+ */
573
+ private stopped(step: Step): void {
574
+ const { instance, graph } = step;
575
+ const settings = graph.document.settings;
576
+ if (instance.parentInstanceId !== null) this.addJob(step, "returned", { payload: { parentInstanceId: instance.parentInstanceId, parentTokenId: instance.parentTokenId } });
577
+ if (settings?.maxConcurrent !== undefined || settings?.sameKey === "queue" || (instance.startedVia === "schedule" && queuesSchedule(graph.document))) this.addJob(step, "release", { payload: { processKey: instance.processKey } });
578
+ // A handler that fails does not start a handler: a chain of them would never end.
579
+ if ((instance.status === "failed" || instance.status === "timedOut") && settings?.errorHandler !== undefined && instance.startedVia !== "errorHandler") {
580
+ this.addJob(step, "errorHandler", { payload: { process: settings.errorHandler } });
581
+ }
292
582
  }
293
583
 
294
584
  /** Adds a history entry to the step. */
@@ -319,27 +609,32 @@ export class WorkflowEngine {
319
609
  step.instance.output = outputOf(step.graph.document, step.instance.vars);
320
610
  this.history(step, null, null, "completed", null);
321
611
  this.finished(step, "completed");
612
+ if (step.graph.document.settings?.runTimeout !== undefined) await this.dropJobs(step, ["runTimeout"]);
613
+ this.stopped(step);
322
614
  }
323
615
  }
324
616
 
325
617
  /** The node under a token: returns the new tokens to move on. */
326
618
  private enter(step: Step, token: WfToken): WfToken[] {
327
619
  const node = step.graph.document.nodes[token.nodeId];
328
- if (!node) {
329
- this.fail(step, token, "unknown_node", `node ${token.nodeId} is not in the version`);
330
- return [];
331
- }
620
+ if (!node) return this.failed(step, token, { code: "unknown_node", message: `node ${token.nodeId} is not in the version` });
332
621
  const role = nodeKindOf(node.kind)?.role;
333
622
  if (role === "start") return this.leave(step, token, this.single(step, token.nodeId));
334
623
  if (role === "end") {
335
624
  this.close(token, "done");
336
- return [];
625
+ return token.parentTokenId === null ? [] : this.bodyEnded(step, token);
337
626
  }
338
627
  // An error boundary that caught a step's failure: it only leads on.
339
628
  if (role === "boundary") return this.leave(step, token, this.single(step, token.nodeId));
340
629
  switch (node.kind) {
341
630
  case "assign":
342
631
  return this.assign(step, token, node);
632
+ case "loop":
633
+ return this.enterLoop(step, token, node);
634
+ case "callProcess":
635
+ token.status = "waiting";
636
+ this.addJob(step, "call", { tokenId: token.id, payload: { fresh: true } });
637
+ return this.arm(step, token, []);
343
638
  case "serviceTask":
344
639
  return this.arm(step, token, this.waitForTool(step, token));
345
640
  case "userTask":
@@ -353,8 +648,7 @@ export class WorkflowEngine {
353
648
  case "parallelGateway":
354
649
  return this.parallel(step, token);
355
650
  default:
356
- this.fail(step, token, "not_supported", `${node.kind} cannot be entered by a flow`);
357
- return [];
651
+ return this.failed(step, token, { code: "not_supported", message: `${node.kind} cannot be entered by a flow` });
358
652
  }
359
653
  }
360
654
 
@@ -369,7 +663,7 @@ export class WorkflowEngine {
369
663
  const reads = masksPersonal(document) ? personalPaths(document) : new Set<string>();
370
664
  const logged: Record<string, unknown> = {};
371
665
  for (const { var: name, value } of assignments) {
372
- const result = evaluateExpression(value, dataOf(step.instance, this.now())) ?? null;
666
+ const result = evaluateExpression(value, dataOf(step.instance, this.now(), token)) ?? null;
373
667
  step.instance.vars = { ...step.instance.vars, [name]: result };
374
668
  logged[name] = personal.has(name) ? PERSONAL_MASK : maskByMapping(value, result, reads);
375
669
  }
@@ -379,13 +673,10 @@ export class WorkflowEngine {
379
673
  }
380
674
 
381
675
  private waitForTimer(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
382
- const dueAt = timerDue(node.config ?? {}, dataOf(step.instance, this.now()), this.now());
383
- if (dueAt === undefined) {
384
- this.fail(step, token, "bad_timer", `the timer of ${token.nodeId} has no valid date`);
385
- return [];
386
- }
676
+ const dueAt = timerDue(node.config ?? {}, dataOf(step.instance, this.now(), token), this.now());
677
+ if (dueAt === undefined) return this.failed(step, token, { code: "bad_timer", message: `the timer of ${token.nodeId} has no valid date` });
387
678
  token.status = "waiting";
388
- this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "timer" as const, instanceId: step.instance.id, tokenId: token.id, dueAt }));
679
+ this.addJob(step, "timer", { tokenId: token.id, dueAt });
389
680
  return [];
390
681
  }
391
682
 
@@ -397,63 +688,55 @@ export class WorkflowEngine {
397
688
  if (host.status !== "waiting") return next;
398
689
  for (const [id, node] of step.graph.boundaries.get(host.nodeId) ?? []) {
399
690
  if (node.kind === "boundaryEvent") {
400
- const correlation = correlationOf(node.config ?? {}, dataOf(step.instance, this.now()));
401
- if (correlation === undefined) {
402
- this.fail(step, host, "bad_correlation", `the correlation of ${id} has no value`);
403
- return [];
404
- }
405
- const watcher = this.spawn(step, id, null);
691
+ const correlation = correlationOf(node.config ?? {}, dataOf(step.instance, this.now(), host));
692
+ if (correlation === undefined) return this.failed(step, host, { code: "bad_correlation", message: `the correlation of ${id} has no value` });
693
+ const watcher = this.spawn(step, id, null, host);
406
694
  watcher.status = "waiting";
407
695
  this.subscribe(step, watcher, String(node.config?.event), correlation);
408
696
  continue;
409
697
  }
410
698
  if (node.kind !== "boundaryTimer") continue;
411
- const dueAt = timerDue(node.config ?? {}, dataOf(step.instance, this.now()), this.now());
412
- if (dueAt === undefined) {
413
- this.fail(step, host, "bad_timer", `the timer of ${id} has no valid date`);
414
- return [];
415
- }
416
- const watcher = this.spawn(step, id, null);
699
+ const dueAt = timerDue(node.config ?? {}, dataOf(step.instance, this.now(), host), this.now());
700
+ if (dueAt === undefined) return this.failed(step, host, { code: "bad_timer", message: `the timer of ${id} has no valid date` });
701
+ const watcher = this.spawn(step, id, null, host);
417
702
  watcher.status = "waiting";
418
- this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "timer" as const, instanceId: step.instance.id, tokenId: watcher.id, dueAt }));
703
+ this.addJob(step, "timer", { tokenId: watcher.id, dueAt });
419
704
  }
420
705
  return next;
421
706
  }
422
707
 
423
- /** The step left or failed: its boundary tokens close; their jobs find the tokens closed and drop. */
424
- private disarm(step: Step, hostNodeId: string, except?: string): void {
708
+ /** The step left or failed: its boundary tokens close; their jobs find the tokens closed and drop. Tokens of other iterations stay. */
709
+ private disarm(step: Step, host: WfToken, except?: string, hostNodeId = host.nodeId): void {
425
710
  const boundaries = new Set((step.graph.boundaries.get(hostNodeId) ?? []).map(([id]) => id));
426
711
  if (boundaries.size === 0) return;
427
712
  for (const token of step.tokens) {
428
- if (token.id !== except && boundaries.has(token.nodeId) && LIVE.has(token.status)) this.close(token, "cancelled");
713
+ if (token.id !== except && boundaries.has(token.nodeId) && LIVE.has(token.status) && sameFrame(token, host)) this.close(token, "cancelled");
429
714
  }
430
715
  }
431
716
 
432
717
  private waitForEvent(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
433
- const correlation = correlationOf(node.config ?? {}, dataOf(step.instance, this.now()));
434
- if (correlation === undefined) {
435
- this.fail(step, token, "bad_correlation", `the correlation of ${token.nodeId} has no value`);
436
- return [];
437
- }
718
+ const correlation = correlationOf(node.config ?? {}, dataOf(step.instance, this.now(), token));
719
+ if (correlation === undefined) return this.failed(step, token, { code: "bad_correlation", message: `the correlation of ${token.nodeId} has no value` });
438
720
  token.status = "waiting";
439
721
  this.subscribe(step, token, String(node.config?.event), correlation);
440
722
  return [];
441
723
  }
442
724
 
443
725
  private subscribe(step: Step, token: WfToken, eventKey: string, correlation: string | null): void {
444
- this.db.subscriptions.add(Object.assign(new WfSubscription(), {
726
+ step.subscriptions.push(Object.assign(new WfSubscription(), {
445
727
  id: Bun.randomUUIDv7(),
446
728
  instanceId: step.instance.id,
447
729
  tokenId: token.id,
448
730
  eventKey,
449
731
  correlation,
450
732
  partition: step.instance.partition,
733
+ createdAt: this.now(),
451
734
  }));
452
735
  }
453
736
 
454
737
  private waitForTool(step: Step, token: WfToken): WfToken[] {
455
738
  token.status = "waiting";
456
- this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "tool" as const, instanceId: step.instance.id, tokenId: token.id, dueAt: this.now() }));
739
+ this.addJob(step, "tool", { tokenId: token.id });
457
740
  return [];
458
741
  }
459
742
 
@@ -482,13 +765,10 @@ export class WorkflowEngine {
482
765
  private choose(step: Step, token: WfToken): WfToken[] {
483
766
  const flows = step.graph.outgoing.get(token.nodeId) ?? [];
484
767
  if (flows.length === 1) return this.leave(step, token, flows[0]!);
485
- const data = dataOf(step.instance, this.now());
768
+ const data = dataOf(step.instance, this.now(), token);
486
769
  const chosen = flows.find(([, flow]) => flow.condition !== undefined && isTruthy(evaluateExpression(flow.condition, data)))
487
770
  ?? flows.find(([, flow]) => flow.isDefault === true);
488
- if (!chosen) {
489
- this.fail(step, token, "no_branch", "no condition matched and there is no default flow");
490
- return [];
491
- }
771
+ if (!chosen) return this.failed(step, token, { code: "no_branch", message: "no condition matched and there is no default flow" });
492
772
  return this.leave(step, token, chosen);
493
773
  }
494
774
 
@@ -500,16 +780,17 @@ export class WorkflowEngine {
500
780
  token.status = "waiting";
501
781
  const arrived = new Map<string, WfToken>();
502
782
  for (const other of step.tokens) {
503
- if (other.nodeId === token.nodeId && other.status === "waiting" && other.viaFlowId !== null && !arrived.has(other.viaFlowId)) arrived.set(other.viaFlowId, other);
783
+ if (other.nodeId === token.nodeId && other.status === "waiting" && other.viaFlowId !== null && !arrived.has(other.viaFlowId) && sameFrame(other, token)) arrived.set(other.viaFlowId, other);
504
784
  }
505
785
  if (!inputs.every(([id]) => arrived.has(id))) return [];
506
786
  for (const joined of arrived.values()) this.close(joined, "done");
507
- current = this.spawn(step, token.nodeId, null);
787
+ // What the branches of an iteration gave meets here.
788
+ current = this.spawn(step, token.nodeId, null, { ...token, locals: mergedLocals([...arrived.values()]) });
508
789
  }
509
790
  const outputs = step.graph.outgoing.get(token.nodeId) ?? [];
510
791
  this.close(current, "done");
511
792
  this.history(step, current, current.nodeId, "left", { flows: outputs.map(([id]) => id) });
512
- return outputs.map(([id, flow]) => this.spawn(step, flow.target, id));
793
+ return outputs.map(([id, flow]) => this.spawn(step, flow.target, id, current));
513
794
  }
514
795
 
515
796
  /** The single outgoing flow of a node; validation guarantees it exists. */
@@ -522,7 +803,106 @@ export class WorkflowEngine {
522
803
  private leave(step: Step, token: WfToken, [flowId, flow]: readonly [string, ProcessFlow]): WfToken[] {
523
804
  this.close(token, "done");
524
805
  this.history(step, token, token.nodeId, "left", { flow: flowId });
525
- return [this.spawn(step, flow.target, flowId)];
806
+ return [this.spawn(step, flow.target, flowId, token)];
807
+ }
808
+
809
+ /** A loop begins, or goes on after a retry: its token waits while the iterations run. */
810
+ private enterLoop(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
811
+ const config = node.config as unknown as LoopConfig;
812
+ if (!isLoopState(token.output)) {
813
+ let items: readonly unknown[] | null = null;
814
+ if (config.over !== undefined) {
815
+ const value = evaluateExpression(config.over, dataOf(step.instance, this.now(), token)) ?? [];
816
+ if (!Array.isArray(value)) return this.failed(step, token, { code: "loop_not_a_list", message: `over of ${token.nodeId} is not a list` });
817
+ if (value.length > config.maxIterations) return this.failed(step, token, { code: "loop_limit", message: `${value.length} elements for ${token.nodeId}, maxIterations is ${config.maxIterations}` });
818
+ items = value;
819
+ }
820
+ token.output = { items, next: 0, skipped: 0, collected: {}, yielded: false } satisfies LoopState;
821
+ }
822
+ token.status = "waiting";
823
+ const armed = this.arm(step, token, []);
824
+ return token.status === "waiting" ? this.iterate(step, token) : armed;
825
+ }
826
+
827
+ /** Begins iterations up to the loop's limit; when nothing is left to begin or to wait for, the loop leaves. */
828
+ private iterate(step: Step, loop: WfToken): WfToken[] {
829
+ const config = step.graph.document.nodes[loop.nodeId]!.config as unknown as LoopConfig;
830
+ const state = loop.output as LoopState;
831
+ if (state.yielded) return [];
832
+ const entry = step.graph.entries.get(loop.nodeId)!;
833
+ const outer = localsOf(loop);
834
+ const frame = (index: number, item: unknown): Locals => ({
835
+ item,
836
+ index,
837
+ vars: { ...outer?.vars, ...(config.item === undefined ? {} : { [config.item]: item }), ...(config.index === undefined ? {} : { [config.index]: index }) },
838
+ nodes: outer?.nodes ?? {},
839
+ });
840
+ let running = new Set(this.childrenOf(step, loop).map((t) => t.iteration)).size;
841
+ let next = state.next;
842
+ const begun: WfToken[] = [];
843
+ const save = (more: Partial<LoopState> = {}) => {
844
+ loop.output = { ...state, next, ...more } satisfies LoopState;
845
+ };
846
+ while (running < (config.parallel?.limit ?? 1)) {
847
+ const item = state.items?.[next] ?? null;
848
+ const more = state.items !== null ? next < state.items.length
849
+ : config.times !== undefined ? next < config.times
850
+ : isTruthy(evaluateExpression(config.while!, dataOf(step.instance, this.now(), { locals: frame(next, null) as unknown as Frame["locals"] })));
851
+ if (!more) break;
852
+ if (next >= config.maxIterations) {
853
+ save();
854
+ return this.failed(step, loop, { code: "loop_limit", message: `${loop.nodeId} reached maxIterations: ${config.maxIterations}` });
855
+ }
856
+ if (step.iterations >= LOOP_BATCH) {
857
+ save({ yielded: true });
858
+ this.addJob(step, "loop", { tokenId: loop.id });
859
+ return begun;
860
+ }
861
+ step.iterations += 1;
862
+ const first = this.spawn(step, entry, null, { parentTokenId: loop.id, iteration: next, locals: frame(next, item) as unknown as Frame["locals"] });
863
+ this.history(step, first, loop.nodeId, "iteration", { iteration: next });
864
+ begun.push(first);
865
+ next += 1;
866
+ running += 1;
867
+ }
868
+ save();
869
+ if (running > 0) return begun;
870
+ const collect = config.collect;
871
+ if (collect !== undefined) step.instance.vars = { ...step.instance.vars, [collect.to]: Object.keys(state.collected).sort((a, b) => Number(a) - Number(b)).map((key) => state.collected[key]) };
872
+ return this.finish(step, loop, { iterations: next, skipped: state.skipped });
873
+ }
874
+
875
+ /** A `loop` job: the next batch of iterations. `false` when the loop no longer waits. */
876
+ async continueLoop(step: Step, tokenId: string): Promise<boolean> {
877
+ const loop = step.tokens.find((t) => t.id === tokenId);
878
+ if (!loop || loop.status !== "waiting" || step.instance.status !== "running" || !isLoopState(loop.output)) return false;
879
+ loop.output = { ...loop.output, yielded: false } satisfies LoopState;
880
+ await this.advance(step, this.iterate(step, loop));
881
+ return true;
882
+ }
883
+
884
+ /** A token of a body reached its end: when it is the last of the iteration, what the loop collects is taken and the next one begins. */
885
+ private bodyEnded(step: Step, token: WfToken): WfToken[] {
886
+ const loop = step.tokens.find((t) => t.id === token.parentTokenId && t.status === "waiting");
887
+ if (!loop || step.tokens.some((t) => t.parentTokenId === loop.id && t.iteration === token.iteration && LIVE.has(t.status))) return [];
888
+ const config = step.graph.document.nodes[loop.nodeId]!.config as unknown as LoopConfig;
889
+ if (config.collect !== undefined) {
890
+ const state = loop.output as LoopState;
891
+ const value = evaluateExpression(config.collect.from, dataOf(step.instance, this.now(), token)) ?? null;
892
+ loop.output = { ...state, collected: { ...state.collected, [String(token.iteration)]: value } } satisfies LoopState;
893
+ }
894
+ return this.iterate(step, loop);
895
+ }
896
+
897
+ /** `onItemError: "skip"`: what still runs in the iteration closes and the loop goes on without it. */
898
+ private skipIteration(step: Step, loop: WfToken, iteration: number, error: StepError): WfToken[] {
899
+ for (const token of this.childrenOf(step, loop)) {
900
+ if (token.iteration === iteration) this.closeTree(step, token, "interrupted");
901
+ }
902
+ const state = loop.output as LoopState;
903
+ loop.output = { ...state, skipped: state.skipped + 1 } satisfies LoopState;
904
+ this.history(step, loop, loop.nodeId, "skipped", { iteration, ...detailsOf(error) });
905
+ return this.iterate(step, loop);
526
906
  }
527
907
 
528
908
  private close(token: WfToken, status: "done" | "cancelled"): void {
@@ -530,15 +910,16 @@ export class WorkflowEngine {
530
910
  token.endedAt = this.now();
531
911
  }
532
912
 
533
- private spawn(step: Step, nodeId: string, viaFlowId: string | null): WfToken {
534
- const token = Object.assign(new WfToken(), { id: Bun.randomUUIDv7(), instanceId: step.instance.id, nodeId, viaFlowId, status: "active" as const });
913
+ /** A new token in the frame of `from`: in the same iteration, it sees what `from` saw. */
914
+ private spawn(step: Step, nodeId: string, viaFlowId: string | null, from: Frame): WfToken {
915
+ const token = Object.assign(new WfToken(), { id: Bun.randomUUIDv7(), instanceId: step.instance.id, nodeId, viaFlowId, status: "active" as const, parentTokenId: from.parentTokenId, iteration: from.iteration, locals: from.locals });
535
916
  this.db.tokens.add(token);
536
917
  step.tokens.push(token);
537
918
  this.history(step, token, nodeId, "entered", viaFlowId ? { flow: viaFlowId } : null);
538
919
  return token;
539
920
  }
540
921
 
541
- private finished(step: Step, status: "completed" | "cancelled"): void {
922
+ private finished(step: Step, status: "completed" | "cancelled" | "timedOut"): void {
542
923
  step.events.push({
543
924
  event: WORKFLOW_INSTANCE_FINISHED as EventToken<unknown>,
544
925
  payload: { instanceId: step.instance.id, processKey: step.instance.processKey, partition: step.instance.partition, status },
@@ -580,15 +961,46 @@ export function correlationOf(config: Readonly<Record<string, unknown>>, data: I
580
961
  return value === undefined || value === null || value === "" || typeof value === "object" ? undefined : String(value);
581
962
  }
582
963
 
583
- /** What expressions read in an instance at this moment of the engine's clock. */
584
- export function dataOf(instance: WfInstance, now: Date): InstanceData {
964
+ /** What expressions read in an instance at this moment of the engine's clock; inside a loop body, with what the iteration has. */
965
+ export function dataOf(instance: WfInstance, now: Date, token?: Pick<Frame, "locals">): InstanceData {
966
+ const locals = token?.locals as unknown as Locals | null | undefined;
585
967
  return {
586
968
  input: instance.input,
587
- vars: instance.vars,
588
- nodes: instance.nodes,
969
+ vars: locals ? { ...instance.vars, ...locals.vars } : instance.vars,
970
+ nodes: locals ? { ...instance.nodes, ...locals.nodes } : instance.nodes,
971
+ ...(locals ? { item: locals.item, index: locals.index } : {}),
589
972
  event: instance.event,
590
973
  trigger: instance.trigger,
591
974
  run: { id: instance.id, processKey: instance.processKey, version: instance.version, partition: instance.partition, test: instance.test },
592
975
  now: now.toISOString(),
593
976
  };
594
977
  }
978
+
979
+ /** Who the steps of an instance act for: `settings.runAs`. */
980
+ export function runActorOf(document: ProcessDocument, instance: WfInstance): WorkflowActor {
981
+ return document.settings?.runAs === "process" ? { kind: "system", id: `process:${instance.processKey}` } : { kind: instance.startedByKind, id: instance.startedById };
982
+ }
983
+
984
+ /** Whether a scheduled run of the process waits for the one before it: `overlap: "queue"`. */
985
+ export function queuesSchedule(document: ProcessDocument): boolean {
986
+ return Object.values(document.nodes).some((node) => node.kind === "scheduleStart" && node.config?.overlap === "queue");
987
+ }
988
+
989
+ function isLoopState(value: unknown): value is LoopState {
990
+ return typeof value === "object" && value !== null && Object.hasOwn(value, "next") && Object.hasOwn(value, "collected");
991
+ }
992
+
993
+ function detailsOf(error: StepError): { code: string; message: string; reason?: string } {
994
+ return { code: error.code, message: error.message, ...(error.reason === undefined ? {} : { reason: error.reason }) };
995
+ }
996
+
997
+ /** What several tokens of one iteration saw, together; the later token wins. */
998
+ function mergedLocals(tokens: readonly WfToken[]): WfToken["locals"] {
999
+ const all = tokens.map(localsOf).filter((locals): locals is Locals => locals !== null);
1000
+ if (all.length === 0) return null;
1001
+ return {
1002
+ ...all[0]!,
1003
+ vars: Object.assign({}, ...all.map((locals) => locals.vars)),
1004
+ nodes: Object.assign({}, ...all.map((locals) => locals.nodes)),
1005
+ };
1006
+ }