bazis 0.133.0 → 0.135.0

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

@@ -1,43 +1,76 @@
-import { inputSpecOf, parseCron, validateForm } from "../../../../library/workflow";
+import { inputSpecOf, parseCron, validateForm, type ProcessNode } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
+import { WorkflowPartitions, type ProcessPartition } from "../../contracts/WorkflowPartitions";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import { WfJob } from "../model/WfJob.model";
 import type { WorkflowEngine } from "./WorkflowEngine";
 
 const SCHEDULE_ACTOR = { kind: "system", id: "schedule" } as const;
+const MINUTE = 60_000;
+
+/** The `config` of a `scheduleStart`, as validation lets it through. */
+interface ScheduleConfig {
+  readonly cron: string;
+  readonly timezone?: string;
+  readonly from?: string;
+  readonly until?: string;
+  readonly overlap?: "skip" | "queue" | "parallel";
+  readonly catchUp?: boolean;
+  readonly partitions?: "none" | "all" | readonly string[];
+}
+
+/** One place a node fires in: a partition with its time zone. */
+interface Target {
+  readonly partition: string | null;
+  readonly timezone: string | undefined;
+}
 
 /**
- * Scheduled starts (`scheduleStart`, cron in UTC). Every latest published
- * version with such nodes has one `schedule` job, due at the nearest firing of
- * any of them. `reconcile` keeps the jobs in line with the catalog; `fire`
- * starts the instances of a due job and plans the next firing in the same
- * transaction, so a crash never starts one firing twice. Firings missed while
- * no worker ran are not caught up: the next one is planned from now.
+ * Scheduled starts (`scheduleStart`). Every node of a latest published version
+ * has a `schedule` job per partition it runs in, due at its next firing.
+ * `reconcile` keeps the jobs in line with the catalog and `WorkflowPartitions`;
+ * `fire` starts the instance of a due job and plans the next firing in the same
+ * transaction, so a crash never starts one firing twice. With `catchUp` the next
+ * firing is planned from the one just made, so every missed firing runs;
+ * otherwise from now, and those missed while no worker ran are gone.
  */
 export class Schedules {
   constructor(
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
     private readonly definitions: IWorkflowDefinitions,
+    private readonly languages: WorkflowLanguages,
+    /** The scope: the application's own `WorkflowPartitions` replaces the default. */
+    private readonly services: ServiceProvider,
   ) {}
 
-  /** Adds jobs for new scheduled versions and drops those of replaced or archived ones. */
+  /** Adds jobs for new scheduled nodes and partitions and drops those no longer wanted. */
   async reconcile(now = this.engine.now()): Promise<void> {
-    const versions = (await this.definitions.published()).filter((version) => scheduleNodes(version).length > 0);
-    const wanted = new Map(versions.map((version) => [version.id, version]));
+    const wanted = new Map<string, { readonly version: VersionDetails; readonly nodeId: string; readonly config: ScheduleConfig; readonly target: Target }>();
+    const invalid: string[] = [];
+    for (const version of await this.definitions.published()) {
+      for (const [nodeId, config] of scheduleNodes(version)) {
+        for (const target of await this.targetsOf(version.key, config)) {
+          if (parseCron(config.cron, target.timezone) === undefined) invalid.push(`${version.key}: time zone ${String(target.timezone)} of partition ${String(target.partition)}`);
+          else wanted.set(keyOf(version.id, nodeId, target.partition), { version, nodeId, config, target });
+        }
+      }
+    }
     const added: WfJob[] = [];
     await this.db.transactionScope(async () => {
       // One reconciler at a time across application instances.
       await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext('bazis.workflow.schedules'))");
       const jobs = await this.db.jobs.asNoTracking().where((j) => j.kind.eq("schedule")).toList();
-      const stale = jobs.filter((job) => job.versionId === null || !wanted.has(job.versionId)).map((job) => job.id);
+      const stale = jobs.filter((job) => !wanted.has(keyOf(job.versionId, job.nodeId, job.partition))).map((job) => job.id);
       if (stale.length > 0) await this.db.jobs.asNoTracking().where((j) => j.id.in(stale)).executeDelete();
-      const planned = new Set(jobs.map((job) => job.versionId));
-      for (const version of versions) {
-        if (planned.has(version.id)) continue;
-        const dueAt = nextFiring(version, now);
+      const planned = new Set(jobs.map((job) => keyOf(job.versionId, job.nodeId, job.partition)));
+      for (const [key, { version, nodeId, config, target }] of wanted) {
+        if (planned.has(key)) continue;
+        const dueAt = nextFiring(config, target, now);
         if (dueAt === undefined) continue;
-        const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "schedule" as const, versionId: version.id, dueAt });
+        const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "schedule" as const, versionId: version.id, nodeId, partition: target.partition, dueAt });
         this.db.jobs.add(job);
         added.push(job);
       }
@@ -45,40 +78,74 @@ export class Schedules {
     });
     // The jobs belong to the worker from now on: this context must not hold them.
     for (const job of added) this.db.detach(job);
+    if (invalid.length > 0) throw new Error(`Scheduled starts are not planned for ${invalid.join("; ")}`);
   }
 
-  /** A `schedule` job is due: start an instance from every node firing at this minute and plan the next firing. */
+  /** A `schedule` job is due: start an instance unless `overlap` says otherwise, and plan the next firing. */
   async fire(job: WfJob): Promise<void> {
     const version = job.versionId === null ? undefined : await this.definitions.versionById(job.versionId);
     const latest = version === undefined ? undefined : (await this.definitions.published()).find((item) => item.id === version.id);
-    if (!latest) {
+    const config = latest === undefined || job.nodeId === null ? undefined : scheduleConfig(latest.document.nodes[job.nodeId]);
+    const target = latest === undefined || config === undefined ? undefined : (await this.targetsOf(latest.key, config)).find((item) => item.partition === job.partition);
+    if (!latest || !config || !target) {
       await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       return;
     }
-    const due = new Date(Math.floor(job.dueAt.getTime() / 60_000) * 60_000);
+    const due = new Date(Math.floor(job.dueAt.getTime() / MINUTE) * MINUTE);
     const graph = this.engine.cache(latest);
+    const { overlap = "parallel" } = config;
     await this.db.transactionScope(async () => {
-      // Planned from now, not from the missed firing: a stopped worker does not catch up.
       const now = this.engine.now();
-      const next = nextFiring(latest, now > due ? now : due);
+      const next = nextFiring(config, target, config.catchUp === true || now <= due ? due : now);
       if (next === undefined) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       else await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: next, lockedUntil: null, attempts: 0, lastError: null });
-      for (const [nodeId, cron] of scheduleNodes(latest)) {
-        if (!cron.matches(due)) continue;
-        await this.engine.begin(graph, nodeId, { input: validateForm(inputSpecOf(latest.document), {}).value, partition: null, businessKey: null, startedVia: "schedule", actor: SCHEDULE_ACTOR });
+      let queued = false;
+      if (overlap !== "parallel") {
+        await this.engine.lockProcess(latest.key);
+        if (await this.engine.scheduledLive(latest.key, target.partition) > 0) {
+          if (overlap === "skip") return;
+          queued = true;
+        }
       }
+      await this.engine.begin(graph, job.nodeId!, { input: validateForm(inputSpecOf(latest.document), {}).value, partition: target.partition, businessKey: null, startedVia: "schedule", actor: SCHEDULE_ACTOR, queued, scheduledAt: due });
     });
   }
+
+  /** Where a node runs: `none` without a partition, `all` in every enabled one, a list in those not switched off. */
+  private async targetsOf(processKey: string, config: ScheduleConfig): Promise<readonly Target[]> {
+    const { partitions = "none", timezone } = config;
+    if (partitions === "none") return [{ partition: null, timezone }];
+    const known = await this.partitionsOf(processKey);
+    if (partitions === "all") return known.filter((item) => item.enabled).map((item) => ({ partition: item.partition, timezone: timezone ?? item.timezone }));
+    return partitions.flatMap((partition) => {
+      const entry = known.find((item) => item.partition === partition);
+      return entry?.enabled === false ? [] : [{ partition, timezone: timezone ?? entry?.timezone }];
+    });
+  }
+
+  private async partitionsOf(processKey: string): Promise<readonly ProcessPartition[]> {
+    return await this.services.resolve(WorkflowPartitions).of(processKey, { partition: null, language: this.languages.default, actor: null });
+  }
+}
+
+function keyOf(versionId: string | null, nodeId: string | null, partition: string | null): string {
+  return JSON.stringify([versionId, nodeId, partition]);
+}
+
+function scheduleConfig(node: ProcessNode | undefined): ScheduleConfig | undefined {
+  return node?.kind === "scheduleStart" && typeof node.config?.cron === "string" ? node.config as unknown as ScheduleConfig : undefined;
 }
 
-function scheduleNodes(version: VersionDetails) {
+function scheduleNodes(version: VersionDetails): readonly (readonly [string, ScheduleConfig])[] {
   return Object.entries(version.document.nodes).flatMap(([id, node]) => {
-    const cron = node.kind === "scheduleStart" && typeof node.config?.cron === "string" ? parseCron(node.config.cron) : undefined;
-    return cron === undefined ? [] : [[id, cron] as const];
+    const config = scheduleConfig(node);
+    return config === undefined ? [] : [[id, config] as const];
   });
 }
 
-function nextFiring(version: VersionDetails, after: Date): Date | undefined {
-  const times = scheduleNodes(version).map(([, cron]) => cron.next(after)?.getTime()).filter((time): time is number => time !== undefined);
-  return times.length === 0 ? undefined : new Date(Math.min(...times));
+/** The first firing after `after` inside the period of the node. */
+function nextFiring(config: ScheduleConfig, target: Target, after: Date): Date | undefined {
+  const from = config.from === undefined ? undefined : new Date(Date.parse(config.from) - MINUTE);
+  const next = parseCron(config.cron, target.timezone)?.next(from !== undefined && from > after ? from : after);
+  return next === undefined || (config.until !== undefined && next.getTime() > Date.parse(config.until)) ? undefined : next;
 }

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

@@ -1,6 +1,8 @@
 import type { AgentSchemaContract, AgentToolResult } from "../../../agent";
-import { durationMs, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, type ProcessDocument } from "../../../../library/workflow";
+import { durationMs, inputReferences, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, type ProcessDocument } from "../../../../library/workflow";
 import type { WorkflowToolMetadata } from "../../contracts/types";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { WorkflowReferences } from "../../internal/WorkflowReferences";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
@@ -23,6 +25,8 @@ export class ToolStep {
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
     private readonly tools: WorkflowTools,
+    private readonly references: WorkflowReferences,
+    private readonly languages: WorkflowLanguages,
   ) {}
 
   async run(job: WfJob, signal: AbortSignal): Promise<void> {
@@ -42,13 +46,22 @@ export class ToolStep {
       await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ lockedUntil: new Date(this.engine.now().getTime() + timeoutMs + LEASE_MS) });
     }
     const runner = this.tools.bound;
+    const trial = instance.test ? runner?.getTool(name)?.metadata.dryRun : undefined;
+    const missing = await this.references.missing(inputReferences(this.references.inputSchemaOf(name), input), { scope: instance.partition, language: this.languages.default });
     const result: AgentToolResult = runner === undefined
       ? { callId: token.id, name, status: "error", error: { code: "TOOL_NOT_FOUND", message: `Tool ${name} is not available to processes` }, metadata: {} } as AgentToolResult
+      : missing.length > 0
+      // A value computed by the process, or one that is gone since the publication (WORKFLOW-002 §6.3).
+      ? { callId: token.id, name, status: "error", error: { code: "ref_not_found", message: `${missing[0]!.kind} ${JSON.stringify(missing[0]!.id)} does not exist`, details: { reason: "ref_not_found", path: missing[0]!.path } }, metadata: {} } as AgentToolResult
+      : trial === "unsupported"
+      // A trial never calls a Tool that cannot run without changing anything.
+      ? { callId: token.id, name, status: "success", output: { dryRun: true }, metadata: {} } as AgentToolResult
       : await runner.run(name, input, {
         idempotencyKey: token.id,
         actor: runActorOf(graph.document, instance),
-        metadata: { instanceId: instance.id, processKey: instance.processKey, nodeId: token.nodeId, partition: instance.partition, test: false } satisfies WorkflowToolMetadata,
+        metadata: { instanceId: instance.id, processKey: instance.processKey, nodeId: token.nodeId, partition: instance.partition, test: instance.test } satisfies WorkflowToolMetadata,
         signal,
+        ...(trial === "supported" ? { dryRun: true } : {}),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
       });
 
@@ -72,6 +85,7 @@ export class ToolStep {
         status: result.status,
         attempt: job.attempts,
         durationMs: result.durationMs ?? null,
+        ...(trial === undefined ? {} : { dryRun: trial === "supported" ? "called" : "not called" }),
         ...payloads,
         ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message, ...(reason === undefined ? {} : { reason }) } } : {}),
         ...(retryAt === undefined ? {} : { retryAt: retryAt.toISOString() }),

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

@@ -4,7 +4,7 @@ import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import type { WorkflowEvents } from "../../internal/WorkflowEvents";
-import { WORKFLOW_INSTANCE_CANCELLED, WORKFLOW_INSTANCE_FINISHED, WORKFLOW_INSTANCE_RETRIED, WORKFLOW_INSTANCE_STARTED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED } from "../events/Runtime.events";
+import { WORKFLOW_INSTANCE_CANCELLED, WORKFLOW_INSTANCE_FINISHED, WORKFLOW_INSTANCE_RETRIED, WORKFLOW_INSTANCE_STARTED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, WORKFLOW_TRIAL_TASK_REQUESTED, WORKFLOW_TRIAL_TOKEN_CLOSED } from "../events/Runtime.events";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import { WfHistory, type HistoryType } from "../model/WfHistory.model";
 import { WfInstance, type StartedVia } from "../model/WfInstance.model";
@@ -49,6 +49,12 @@ export interface BeginOptions {
   readonly parent?: { readonly instanceId: string; readonly tokenId: string; readonly depth: number };
   /** What led to the start: `$trigger.cause`. */
   readonly cause?: Readonly<Record<string, unknown>>;
+  /** It waits as `pending` whatever the limits say: `overlap: "queue"`. */
+  readonly queued?: boolean;
+  /** The firing a scheduled start belongs to: `$trigger.scheduledAt`. */
+  readonly scheduledAt?: Date;
+  /** A trial run (WORKFLOW-002 §5.4): takes no place among real ones and tells the application nothing. */
+  readonly test?: boolean;
 }
 
 /** Why a step failed. `reason` is the business reason an error boundary may name. */
@@ -158,9 +164,10 @@ export class WorkflowEngine {
    */
   async begin(graph: ProcessGraph, startNodeId: string, options: BeginOptions): Promise<Begun> {
     return await this.db.transactionScope(async (transaction) => {
-      const admission = await this.admit(graph, options.businessKey);
+      const admission = options.test === true ? "start" : await this.admit(graph, options.businessKey);
       if (typeof admission === "object") return { id: admission.skippedBy, skipped: true };
-      const instance = this.newInstance(graph, options, admission === "queue" ? "pending" : "running");
+      const waits = admission === "queue" || options.queued === true;
+      const instance = this.newInstance(graph, options, waits ? "pending" : "running");
       this.db.instances.add(instance);
       await this.db.saveChanges();
       const step = this.stepOf(instance, [], graph);
@@ -170,7 +177,7 @@ export class WorkflowEngine {
         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 },
       });
       const first = this.spawn(step, startNodeId, null, TOP);
-      if (admission === "queue") {
+      if (waits) {
         first.status = "waiting";
         this.history(step, first, startNodeId, "queued", null);
       } else {
@@ -206,7 +213,7 @@ export class WorkflowEngine {
     await this.lockProcess(graph.processKey);
     if (keyed) {
       const same = await this.db.instances.asNoTracking()
-        .where((i) => i.processKey.eq(graph.processKey).and(i.businessKey.eq(businessKey)).and(i.status.in(["pending", "running", "failed"])))
+        .where((i) => i.processKey.eq(graph.processKey).and(i.businessKey.eq(businessKey)).and(i.test.eq(false)).and(i.status.in(["pending", "running", "failed"])))
         .firstOrDefault();
       if (same) return sameKey === "skip" ? { skippedBy: same.id } : "queue";
     }
@@ -219,7 +226,14 @@ export class WorkflowEngine {
   }
 
   async runningOf(processKey: string): Promise<number> {
-    return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.status.eq("running"))).count();
+    return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.status.eq("running"))).count();
+  }
+
+  /** 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. */
+  async scheduledLive(processKey: string, partition: string | null): Promise<number> {
+    return await this.db.instances.asNoTracking()
+      .where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.startedVia.eq("schedule")).and(i.status.in(["pending", "running"])).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)))
+      .count();
   }
 
   /** A `pending` instance got its place: its token moves from the start. */
@@ -243,6 +257,7 @@ export class WorkflowEngine {
       processKey: graph.processKey,
       version: graph.version,
       partition: options.partition,
+      test: options.test === true,
       input: options.input,
       vars: initialVarsOf(graph.document),
       event: options.event?.payload ?? null,
@@ -253,6 +268,7 @@ export class WorkflowEngine {
         ...(options.event === undefined ? {} : { eventKey: options.event.key }),
         ...(options.cause === undefined ? {} : { cause: options.cause }),
         ...(options.parent === undefined ? {} : { depth: options.parent.depth }),
+        ...(options.scheduledAt === undefined ? {} : { scheduledAt: options.scheduledAt.toISOString() }),
       },
       businessKey: options.businessKey,
       startedVia: options.startedVia,
@@ -418,6 +434,14 @@ export class WorkflowEngine {
     return await this.fireBoundary(step, token, node, { firedAt }, "timer");
   }
 
+  /** Whether the step takes this event: `eventWait.until` may leave it waiting for the next one. */
+  eventAccepted(step: Step, tokenId: string, payload: Record<string, unknown>): boolean {
+    const token = step.tokens.find((t) => t.id === tokenId);
+    const node = token === undefined ? undefined : step.graph.document.nodes[token.nodeId];
+    if (token === undefined || node?.kind !== "eventWait" || node.config?.until === undefined || token.status !== "waiting") return true;
+    return isTruthy(evaluateExpression(node.config.until as Expr, { ...dataOf(step.instance, this.now(), token), event: payload }));
+  }
+
   /**
    * An event the token waits for arrived. An `eventWait` step moves on with
    * the payload (and `saveTo`); a `boundaryEvent` takes its flow like a
@@ -553,7 +577,7 @@ export class WorkflowEngine {
     const { instance, graph } = step;
     const settings = graph.document.settings;
     if (instance.parentInstanceId !== null) this.addJob(step, "returned", { payload: { parentInstanceId: instance.parentInstanceId, parentTokenId: instance.parentTokenId } });
-    if (settings?.maxConcurrent !== undefined || settings?.sameKey === "queue") this.addJob(step, "release", { payload: { processKey: instance.processKey } });
+    if (settings?.maxConcurrent !== undefined || settings?.sameKey === "queue" || (instance.startedVia === "schedule" && queuesSchedule(graph.document))) this.addJob(step, "release", { payload: { processKey: instance.processKey } });
     // A handler that fails does not start a handler: a chain of them would never end.
     if ((instance.status === "failed" || instance.status === "timedOut") && settings?.errorHandler !== undefined && instance.startedVia !== "errorHandler") {
       this.addJob(step, "errorHandler", { payload: { process: settings.errorHandler } });
@@ -907,14 +931,24 @@ export class WorkflowEngine {
 
   /** Events go out after the commit, so a handler never sees a step that rolled back. */
   private publishAfter(transaction: { afterCommit(callback: () => void | Promise<void>): void }, step: Step): void {
-    if (step.events.length === 0) return;
-    const events = [...step.events];
+    const events = step.instance.test ? trialEvents(step) : [...step.events];
+    if (events.length === 0) return;
     transaction.afterCommit(async () => {
       for (const { event, payload } of events) await this.events.publish(event, payload);
     });
   }
 }
 
+/** What a trial run tells: only what its tasks need, and they go to who started it. */
+function trialEvents(step: Step): PendingEvent[] {
+  const { instance } = step;
+  return step.events.flatMap(({ event, payload }): PendingEvent[] => {
+    if (event === (WORKFLOW_TOKEN_CLOSED as EventToken<unknown>)) return [{ event: WORKFLOW_TRIAL_TOKEN_CLOSED as EventToken<unknown>, payload }];
+    if (event !== (WORKFLOW_TASK_REQUESTED as EventToken<unknown>)) return [];
+    return [{ event: WORKFLOW_TRIAL_TASK_REQUESTED as EventToken<unknown>, payload: { ...(payload as object), assignee: { user: instance.startedById } } }];
+  });
+}
+
 /** When a timer fires: `duration` from now, or the date at the `at` path; `undefined` if neither is valid. */
 export function timerDue(config: Readonly<Record<string, unknown>>, data: InstanceData, now: Date): Date | undefined {
   if (typeof config.duration === "string") {
@@ -960,6 +994,11 @@ export function runActorOf(document: ProcessDocument, instance: WfInstance): Wor
   return document.settings?.runAs === "process" ? { kind: "system", id: `process:${instance.processKey}` } : { kind: instance.startedByKind, id: instance.startedById };
 }
 
+/** Whether a scheduled run of the process waits for the one before it: `overlap: "queue"`. */
+export function queuesSchedule(document: ProcessDocument): boolean {
+  return Object.values(document.nodes).some((node) => node.kind === "scheduleStart" && node.config?.overlap === "queue");
+}
+
 function isLoopState(value: unknown): value is LoopState {
   return typeof value === "object" && value !== null && Object.hasOwn(value, "next") && Object.hasOwn(value, "collected");
 }

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

@@ -4,6 +4,7 @@ import { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
 import { ChildCalls } from "./ChildCalls";
 import { RunLimits } from "./RunLimits";
+import { EventDelivery } from "./EventDelivery";
 import { Schedules } from "./Schedules";
 import { TimerStep } from "./TimerStep";
 import { LEASE_MS, ToolStep } from "./ToolStep";
@@ -81,6 +82,12 @@ export class WorkflowJobs {
         case "errorHandler":
           await scope.resolve(RunLimits).errorHandler(job);
           break;
+        case "event":
+          await scope.resolve(EventDelivery).deliverLater(job);
+          break;
+        case "eventStart":
+          await scope.resolve(EventDelivery).startLater(job);
+          break;
         default:
           await scope.resolve(ToolStep).run(job, signal);
       }

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

@@ -7,9 +7,10 @@ import { WfInstance } from "./WfInstance.model";
  * `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.
+ * starts the process that handles a failure. `event` delivers what `emitLater`
+ * wrote, `eventStart` starts a process by an event after `delay` or `debounce`.
  */
-export type JobKind = "tool" | "timer" | "schedule" | "loop" | "call" | "returned" | "cancelChildren" | "runTimeout" | "release" | "errorHandler";
+export type JobKind = "tool" | "timer" | "schedule" | "loop" | "call" | "returned" | "cancelChildren" | "runTimeout" | "release" | "errorHandler" | "event" | "eventStart";
 
 /**
  * Deferred work of the worker, created in the same transaction as the waiting
@@ -26,7 +27,7 @@ export class WfJob {
   @Column({ type: "text" })
   kind: JobKind = "tool";
 
-  /** `null` for a `schedule` job: its instance does not exist yet. */
+  /** `null` for `schedule`, `event` and `eventStart` jobs: the instance does not exist yet. */
   @Index()
   @Column({ type: "text", nullable: true })
   instanceId: string | null = null;
@@ -35,7 +36,7 @@ export class WfJob {
   @Column({ type: "text", nullable: true })
   tokenId: string | null = null;
 
-  /** The version a `schedule` job starts. */
+  /** The version a `schedule` or `eventStart` job starts. */
   @Column({ type: "text", nullable: true })
   versionId: string | null = null;
 
@@ -47,12 +48,12 @@ export class WfJob {
   @Column({ type: "json", nullable: true })
   payload: unknown = null;
 
-  /** Jobs with one key merge into the last: `debounce` of an event start (stage 4). */
+  /** Jobs with one key merge into the last: `debounce` of an event start. */
   @Index()
   @Column({ type: "text", nullable: true })
   dedupeKey: string | null = null;
 
-  /** The partition and the start node of a `schedule` job (stage 4). */
+  /** The partition and the start node of a `schedule` or `eventStart` job. */
   @Column({ type: "text", nullable: true })
   partition: string | null = null;
 

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

@@ -1,5 +1,6 @@
 import type { AccessFilter } from "../../../access";
 import type { FormIssue } from "../../../../library/workflow";
+import type { OrmTransaction } from "../../../orm";
 import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { HistoryType } from "../model/WfHistory.model";
 import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
@@ -15,6 +16,11 @@ export interface StartInstance extends WorkflowAuditOptions {
   readonly actor: WorkflowActor;
   /** The language of the request, for the application's validator; `workflow.language` by default. */
   readonly language?: string;
+  /**
+   * A trial run (WORKFLOW-002 §5.4): Tools change nothing, the application hears
+   * nothing, tasks go only to who started it. It lives for a day.
+   */
+  readonly test?: boolean;
 }
 
 /** One element of a mass start. */
@@ -62,8 +68,14 @@ export interface InstanceSummary {
   /** The instance whose `callProcess` started this one. */
   readonly parentInstanceId: string | null;
   readonly error: { readonly node: string; readonly code: string; readonly message: string } | null;
+  /** The step it failed on. */
+  readonly failedNode: string | null;
+  /** A trial run. */
+  readonly test: boolean;
   readonly createdAt: Date;
   readonly endedAt: Date | null;
+  /** How long it took by the engine's clock; `null` until it ends. */
+  readonly durationMs: number | null;
 }
 
 export interface TokenDetails {
@@ -99,13 +111,23 @@ export interface HistoryEntry {
   readonly at: Date;
 }
 
+/** What led to an event: `$trigger.cause` of the instances it starts. `instanceId` makes `ignoreOwn` work. */
+export interface EmitCause {
+  readonly instanceId?: string;
+  readonly [key: string]: unknown;
+}
+
 export interface EmitOptions extends WorkflowAuditOptions {
   /** Which waits it is for: `order:42`. Waits without a correlation take any event of the key. */
   readonly correlation?: string | null;
-  /** Only the waits of this partition; it is also the partition of instances the event starts. */
+  /**
+   * Only the waits of this partition; it is also the partition of instances the
+   * event starts, and only processes `WorkflowPartitions` connects to it start.
+   */
   readonly partition?: string | null;
   /** On whose behalf started instances run; `{ kind: "system", id: "event:<key>" }` by default. */
   readonly actor?: WorkflowActor;
+  readonly cause?: EmitCause | null;
 }
 
 export interface EmitResult {
@@ -113,6 +135,8 @@ export interface EmitResult {
   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 }[];
+  /** Processes that start later: `debounce` or `delay` of their `eventStart`. */
+  readonly deferred: readonly { readonly processKey: string }[];
   /** Instances whose `eventWait` or `boundaryEvent` took the event. */
   readonly continued: readonly string[];
   /** Processes with an `eventStart` whose input the payload did not pass. */
@@ -128,6 +152,8 @@ export interface InstanceListQuery extends WorkflowPaging {
   readonly businessKey?: string;
   readonly startedById?: string;
   readonly parentInstanceId?: string;
+  /** Trial runs are hidden unless asked for: `true` gives only them. Children of a named parent are shown as they are. */
+  readonly test?: boolean;
 }
 
 /**
@@ -150,6 +176,13 @@ export abstract class IWorkflowRuntime {
    * `eventStart` for the key, and moves the instances waiting for it.
    */
   abstract emit(eventKey: string, payload?: unknown, options?: EmitOptions): Promise<EmitResult>;
+  /**
+   * Writes an event in the application's transaction: it is delivered as `emit`
+   * after the commit and is gone with a rollback. Needs the same `DatabaseProvider`
+   * as the process tables. Who it reached is not known at this point: a payload a
+   * process refuses goes to the log.
+   */
+  abstract emitLater(tx: OrmTransaction, eventKey: string, payload?: unknown, options?: EmitOptions): Promise<void>;
   /** Instances, newest first. */
   abstract instances(query?: InstanceListQuery): Promise<WorkflowPage<InstanceSummary>>;
   abstract instance(instanceId: string): Promise<InstanceDetails>;