bazis 0.133.0 → 0.134.0

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

@@ -3,12 +3,12 @@ import { WorkflowError } from "../../contracts/WorkflowError";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
-import type { WorkflowEngine } from "./WorkflowEngine";
+import { queuesSchedule, type WorkflowEngine } from "./WorkflowEngine";
 
 /** How many waiting instances of a process one pass looks at. */
 const RELEASE_BATCH = 1000;
 
-/** What a whole run is limited by and what follows its failure: `runTimeout`, `maxConcurrent`, `sameKey: "queue"`, `errorHandler`. */
+/** What a whole run is limited by and what follows its failure: `runTimeout`, `maxConcurrent`, `sameKey: "queue"`, `overlap: "queue"`, `errorHandler`. */
 export class RunLimits {
   constructor(
     private readonly db: RuntimeDbContext,
@@ -47,9 +47,11 @@ export class RunLimits {
       await this.engine.lockProcess(processKey);
       let running = await this.engine.runningOf(processKey);
       for (const row of waiting) {
-        const { maxConcurrent, sameKey } = graphs.get(row.id)!.document.settings ?? {};
+        const { document } = graphs.get(row.id)!;
+        const { maxConcurrent, sameKey } = document.settings ?? {};
         if (maxConcurrent !== undefined && running >= maxConcurrent) continue;
         if (sameKey === "queue" && row.businessKey !== null && await this.keyTaken(processKey, row.businessKey, row.id)) continue;
+        if (row.startedVia === "schedule" && queuesSchedule(document) && await this.scheduleTaken(processKey, row.partition, row.id)) continue;
         const released = await this.engine.inStep(row.id, async (step) => {
           if (step.instance.status !== "pending") return false;
           await this.engine.release(step);
@@ -68,6 +70,14 @@ export class RunLimits {
     return same > 0;
   }
 
+  /** Whether a scheduled run of the partition goes on, or waits since before this one. */
+  private async scheduleTaken(processKey: string, partition: string | null, id: string): Promise<boolean> {
+    const same = await this.db.instances.asNoTracking()
+      .where((i) => i.processKey.eq(processKey).and(i.startedVia.eq("schedule")).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)).and(i.status.eq("running").or(i.status.eq("pending").and(i.id.lt(id)))))
+      .count();
+    return same > 0;
+  }
+
   /** An `errorHandler` job: the handler starts with `$event` telling what happened. What keeps it from starting goes to the history of the instance that failed. */
   async errorHandler(job: WfJob): Promise<void> {
     const failed = job.instanceId === null ? undefined : await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(job.instanceId!));

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

@@ -0,0 +1,13 @@
+import { WorkflowProcessUsage } from "../../contracts/WorkflowProcessUsage";
+import type { RuntimeDbContext } from "../model/Runtime.dbContext";
+
+/** Unfinished instances of a process: they stop it from being deleted. */
+export class RuntimeProcessUsage extends WorkflowProcessUsage {
+  constructor(private readonly db: RuntimeDbContext) {
+    super();
+  }
+
+  async liveInstances(processKey: string): Promise<number> {
+    return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.status.in(["pending", "running", "failed"]))).count();
+  }
+}

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/WorkflowEngine.ts

@@ -49,6 +49,10 @@ 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;
 }
 
 /** Why a step failed. `reason` is the business reason an error boundary may name. */
@@ -160,7 +164,8 @@ export class WorkflowEngine {
     return await this.db.transactionScope(async (transaction) => {
       const admission = 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 +175,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 {
@@ -222,6 +227,13 @@ export class WorkflowEngine {
     return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).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.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. */
   async release(step: Step): Promise<void> {
     if (step.instance.status !== "pending") return;
@@ -253,6 +265,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 +431,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 +574,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 } });
@@ -960,6 +981,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";
@@ -99,13 +100,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 +124,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. */
@@ -150,6 +163,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>;

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

@@ -1,16 +1,18 @@
 import { grantsToWhere } from "../../../access";
-import { paginate } from "../../../orm";
-import { inputSpecOf, type FormIssue, type FormSpec } from "../../../../library/workflow";
+import { paginate, type OrmTransaction } from "../../../orm";
+import { inputSpecOf, type FormSpec } from "../../../../library/workflow";
 import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import type { ServiceProvider } from "../../../di";
 import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
 import type { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { EventDelivery, EventMessage } from "../internal/EventDelivery";
 import type { WorkflowEngine } from "../internal/WorkflowEngine";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfHistory } from "../model/WfHistory.model";
 import type { WfInstance } from "../model/WfInstance.model";
+import { WfJob } from "../model/WfJob.model";
 import type { WfToken } from "../model/WfToken.model";
 import {
   IWorkflowRuntime,
@@ -35,6 +37,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
   constructor(
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
+    private readonly delivery: EventDelivery,
     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,
@@ -135,45 +138,14 @@ export class WorkflowRuntime extends IWorkflowRuntime {
   }
 
   async emit(eventKey: string, payload: unknown = {}, options: EmitOptions = {}): Promise<EmitResult> {
-    if (typeof eventKey !== "string" || !EVENT_KEY.test(eventKey)) throw new WorkflowError("invalid_input", "eventKey must look like payments.received");
-    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new WorkflowError("invalid_input", "payload must be a JSON object");
-    const data = payload as Record<string, unknown>;
-    const correlation = optionalText(options.correlation, "correlation");
-    const partition = optionalText(options.partition, "partition");
-    const actor = options.actor ?? { kind: "system" as const, id: `event:${eventKey}` };
-    actorOf(actor);
-
-    let waits = this.db.subscriptions.asNoTracking().where((s) => s.eventKey.eq(eventKey));
-    waits = correlation === null ? waits.where((s) => s.correlation.isNull()) : waits.where((s) => s.correlation.isNull().or(s.correlation.eq(correlation)));
-    if (partition !== null) waits = waits.where((s) => s.partition.eq(partition));
-    const continued = new Set<string>();
-    for (const wait of await waits.orderBy((s) => s.id).toList()) {
-      const moved = await this.engine.inStep(wait.instanceId, async (step) => {
-        await this.db.subscriptions.asNoTracking().where((s) => s.id.eq(wait.id)).executeDelete();
-        return await this.engine.eventReceived(step, wait.tokenId, eventKey, data);
-      });
-      if (moved === true) continued.add(wait.instanceId);
-    }
+    return await this.delivery.emit(messageOf(eventKey, payload, options));
+  }
 
-    const started: string[] = [];
-    const skipped: { processKey: string; instanceId: string }[] = [];
-    const rejected: { processKey: string; issues: readonly FormIssue[] }[] = [];
-    for (const version of await this.definitions.published()) {
-      for (const [nodeId, node] of Object.entries(version.document.nodes)) {
-        if (node.kind !== "eventStart" || node.config?.event !== eventKey) continue;
-        // An event carries more than a process needs: fields the input does not declare are dropped, not refused.
-        const { value, issues: all } = await this.validator().validate(inputSpecOf(version.document), data, { purpose: "input", processKey: version.key, partition, language: this.languages.default, actor });
-        const issues = all.filter((issue) => issue.code !== "unknown");
-        if (issues.length > 0) {
-          rejected.push({ processKey: version.key, issues });
-          continue;
-        }
-        const begun = await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null, event: { key: eventKey, payload: data } });
-        if (begun.skipped) skipped.push({ processKey: version.key, instanceId: begun.id });
-        else started.push(begun.id);
-      }
-    }
-    return { started, skipped, continued: [...continued], rejected };
+  async emitLater(tx: OrmTransaction, eventKey: string, payload: unknown = {}, options: EmitOptions = {}): Promise<void> {
+    const message = messageOf(eventKey, payload, options);
+    const now = this.engine.now();
+    const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "event" as const, partition: message.partition, dueAt: now, payload: message, createdAt: now });
+    await tx.use(this.db, (db) => db.jobs.insertIfAbsent(job, { conflictBy: (j) => [j.id] }));
   }
 
   async instances(query: InstanceListQuery = {}): Promise<WorkflowPage<InstanceSummary>> {
@@ -214,6 +186,23 @@ export class WorkflowRuntime extends IWorkflowRuntime {
   }
 }
 
+/** An event as the delivery takes it; what cannot be delivered is refused here. */
+function messageOf(eventKey: string, payload: unknown, options: EmitOptions): EventMessage {
+  if (typeof eventKey !== "string" || !EVENT_KEY.test(eventKey)) throw new WorkflowError("invalid_input", "eventKey must look like payments.received");
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new WorkflowError("invalid_input", "payload must be a JSON object");
+  const actor = options.actor ?? { kind: "system" as const, id: `event:${eventKey}` };
+  actorOf(actor);
+  return {
+    eventKey,
+    payload: payload as Record<string, unknown>,
+    correlation: optionalText(options.correlation, "correlation"),
+    partition: optionalText(options.partition, "partition"),
+    actor,
+    request: options.request ?? null,
+    cause: options.cause ?? null,
+  };
+}
+
 function notFound(instanceId: string): WorkflowError {
   return new WorkflowError("not_found", `Instance ${instanceId} does not exist`);
 }