bazis 0.133.0 → 0.134.0

package/core/workflow/contracts/WorkflowPartitions.ts

@@ -0,0 +1,29 @@
+import type { WorkflowPortContext } from "./WorkflowExtensions";
+
+/** A partition a process is connected to. */
+export interface ProcessPartition {
+  /** `null`: the process runs without a partition. */
+  readonly partition: string | null;
+  /** An IANA time zone for the schedules of this partition; a time zone on the node goes first. */
+  readonly timezone?: string;
+  /** A process that is switched off here takes no events and no scheduled starts. */
+  readonly enabled: boolean;
+}
+
+/**
+ * Where a process works (WORKFLOW-002 §6): tenants, spaces, organizations. An
+ * event starts a process only in a partition listed here, a schedule with
+ * `partitions: "all"` runs in every enabled one, and a process connected to a
+ * partition cannot be deleted. The application registers its implementation in
+ * any module.
+ */
+export abstract class WorkflowPartitions {
+  abstract of(processKey: string, context: WorkflowPortContext): readonly ProcessPartition[] | Promise<readonly ProcessPartition[]>;
+}
+
+/** By default a process has one place to work: no partition. */
+export class DefaultWorkflowPartitions extends WorkflowPartitions {
+  of(): readonly ProcessPartition[] {
+    return [{ partition: null, enabled: true }];
+  }
+}

package/core/workflow/contracts/WorkflowProcessUsage.ts

@@ -0,0 +1,8 @@
+/**
+ * What the catalog asks before it deletes a process. Runtime answers: the catalog
+ * knows nothing of instances, and without Runtime there are none.
+ */
+export abstract class WorkflowProcessUsage {
+  /** How many `pending`, `running` and `failed` instances the process has. */
+  abstract liveInstances(processKey: string): Promise<number>;
+}

package/core/workflow/definitions_module/WorkflowDefinitions.module.ts

@@ -3,6 +3,7 @@ import { HOSTED_SERVICE, Module, scoped, singleton } from "../../di";
 import { SystemWorkflowClock, WorkflowClock } from "../contracts/WorkflowClock";
 import { workflowConfig } from "../contracts/Workflow.config";
 import { DefaultWorkflowExtensions, WorkflowExtensions } from "../contracts/WorkflowExtensions";
+import { DefaultWorkflowPartitions, WorkflowPartitions } from "../contracts/WorkflowPartitions";
 import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowLanguages } from "../internal/WorkflowLanguages";
 import { WorkflowTools } from "../internal/WorkflowTools";
@@ -10,6 +11,7 @@ import { definitionsPermissions } from "./access/Definitions.permissions";
 import { FolderReferences } from "./access/Folder.references";
 import { ProcessReferences } from "./access/Process.references";
 import { ProcessFolderLookup } from "./access/ProcessFolder.lookup";
+import { ProcessPartitionLookup } from "./access/ProcessPartition.lookup";
 import { CatalogImport } from "./code/CatalogImport";
 import { CodeProcessCatalog } from "./code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "./code/CodeProcessPublisher";
@@ -23,7 +25,8 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
 /**
  * The process catalog: drafts and published versions, and the processes
  * declared in code ([passport](MODULE.md)). The application checks its own
- * `extensions` by registering its `WorkflowExtensions`.
+ * `extensions` by registering its `WorkflowExtensions` and says where processes
+ * work by registering its `WorkflowPartitions`.
  */
 @Module({
   imports: [AccessModule],
@@ -37,15 +40,17 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(CodeProcessCatalog),
     singleton(WorkflowLanguages),
     singleton(WorkflowExtensions, DefaultWorkflowExtensions),
+    singleton(WorkflowPartitions, DefaultWorkflowPartitions),
     scoped(WorkflowEvents),
     scoped(CatalogImport),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
     scoped(ProcessReferences),
     scoped(FolderReferences),
     scoped(ProcessFolderLookup),
+    scoped(ProcessPartitionLookup),
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],
-  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, ProcessFolderLookup],
+  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, WorkflowPartitions, ProcessFolderLookup],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/access/Definitions.permissions.ts

@@ -1,16 +1,18 @@
 import { definePermissions } from "../../../access";
+import { ProcessPartitionLookup } from "./ProcessPartition.lookup";
 
 const process = { ref: "workflow.process", column: "key" };
 const folder = { ref: "workflow.folder", column: "folder" };
 
 /**
  * The rights of the process catalog (WORKFLOW-002 §6.2). A process is one per
- * application, so these have no partition until `WorkflowPartitions` connects
- * processes to partitions (stage 4).
+ * application: only reading it has partitions, those `WorkflowPartitions`
+ * connects it to.
  */
 export const definitionsPermissions = definePermissions({
   "workflow.processes.read": {
     title: { en: "See processes", ru: "Видеть процессы" },
+    scope: { lookup: ProcessPartitionLookup },
     on: { process, folder },
   },
   "workflow.processes.manage": {

package/core/workflow/definitions_module/access/ProcessPartition.lookup.ts

@@ -0,0 +1,27 @@
+import { AttributeLookup, type AccessValue, type LookupColumn } from "../../../access";
+import type { ServiceProvider } from "../../../di";
+import { WorkflowPartitions } from "../../contracts/WorkflowPartitions";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+
+/** The partitions of a process are not a column: partition → the keys of the processes connected to it (WORKFLOW-002 §6.2). */
+export class ProcessPartitionLookup extends AttributeLookup {
+  constructor(
+    private readonly db: DefinitionsDbContext,
+    private readonly languages: WorkflowLanguages,
+    private readonly services: ServiceProvider,
+  ) {
+    super();
+  }
+
+  async toColumn(values: readonly AccessValue[]): Promise<LookupColumn> {
+    const port = this.services.resolve(WorkflowPartitions);
+    const rows = await this.db.processes.asNoTracking().select((p) => ({ key: p.key })).toList();
+    const keys: string[] = [];
+    for (const { key } of rows) {
+      const partitions = await port.of(key, { partition: null, language: this.languages.default, actor: null });
+      if (partitions.some((item) => item.enabled && values.includes(item.partition))) keys.push(key);
+    }
+    return { column: "key", in: keys };
+  }
+}

package/core/workflow/definitions_module/events/Definitions.events.ts

@@ -1,7 +1,7 @@
 import { createEventToken } from "../../../kernel";
 import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 
-export type ProcessChange = "created" | "updated" | "draftSaved" | "published" | "archived" | "restored";
+export type ProcessChange = "created" | "updated" | "draftSaved" | "published" | "archived" | "restored" | "deleted";
 
 /** A process of the catalog changed, for the application's audit. Published after the commit. */
 export interface WorkflowProcessChanged {

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -1,7 +1,7 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
 import { can, type AccessObject } from "../../../access";
 import type { LocalizedText } from "../../../../library/workflow";
-import { Authorize, Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
+import { Authorize, Controller, Created, Delete, Get, Patch, Post, Put, type HttpContext } from "../../../http";
 import { buildListDocument } from "../../../../library/jsonapi";
 import { body, callerOf, defaultLanguage, filterOf, listQuery, optionalInteger, optionalString, optionalText, pagingOfList, param, requiredString, withTitleText } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
@@ -52,10 +52,20 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async get(ctx: HttpContext) {
     const key = param(ctx, "key");
-    const { language } = await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
+    const { language } = await callerOf(ctx, "workflow.processes.read", await this.readObjectOf(key));
     return withTitleText(await this.definitions.get(key), language, defaultLanguage(ctx));
   }
 
+  /** An archived process without unfinished instances and partitions (WORKFLOW-002 §4.3). */
+  @Delete("processes/:key")
+  @Authorize(can("workflow.processes.manage"))
+  async remove(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    const { actor, request } = await callerOf(ctx, "workflow.processes.manage", await this.objectOf(key));
+    await this.definitions.remove(key, actor, { request });
+    ctx.res.status(204);
+  }
+
   @Patch("processes/:key")
   @Authorize(can("workflow.processes.manage"))
   async update(ctx: HttpContext) {
@@ -102,7 +112,7 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async versions(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
+    await callerOf(ctx, "workflow.processes.read", await this.readObjectOf(key));
     return { data: await this.definitions.versions(key) };
   }
 
@@ -110,7 +120,7 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async version(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await callerOf(ctx, "workflow.processes.read", await this.objectOf(key));
+    await callerOf(ctx, "workflow.processes.read", await this.readObjectOf(key));
     const version = optionalInteger(param(ctx, "version"), "version");
     if (version === undefined) throw new WorkflowError("invalid_input", "version must be an integer");
     return await this.definitions.version(key, version);
@@ -144,6 +154,11 @@ export class ProcessesController {
     return { process: key, folder: await this.definitions.folderOf(key) };
   }
 
+  /** Reading a process is allowed by the partitions it works in. */
+  private async readObjectOf(key: string): Promise<AccessObject> {
+    return { ...await this.objectOf(key), scope: await this.definitions.partitionsOf(key) };
+  }
+
   private localized(items: readonly ProcessSummary[], language: string, ctx: HttpContext) {
     return items.map((item) => withTitleText(item, language, defaultLanguage(ctx)));
   }

package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts

@@ -102,6 +102,8 @@ export abstract class IWorkflowDefinitions {
   abstract get(key: string): Promise<ProcessDetails>;
   /** The folder of a process, for a check of rights; `null` also for a process that does not exist. */
   abstract folderOf(key: string): Promise<string | null>;
+  /** The partitions a process works in, for a check of rights. */
+  abstract partitionsOf(key: string): Promise<readonly (string | null)[]>;
   /** Every finding of a document, with the application's `extensions` checks; nothing is stored. */
   abstract validate(document: unknown, options?: ValidateOptions): Promise<readonly ProcessIssue[]>;
   /** What a designer builds its forms from: node kinds, functions, paths and Tools. */
@@ -109,6 +111,12 @@ export abstract class IWorkflowDefinitions {
   abstract create(process: CreateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
   /** A process declared in code takes only `archived`; other fields give `conflict`. */
   abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
+  /**
+   * Deletes an archived process with its versions: `wrong_status` when it is not
+   * archived, `conflict` when it is declared in code, `in_use` when it has unfinished
+   * instances or partitions. Finished instances and their history stay.
+   */
+  abstract remove(key: string, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<void>;
   /** Stores the draft even with errors; `conflict` for a process declared in code and when `expected` is out of date. */
   abstract saveDraft(key: string, document: unknown, actor: WorkflowActor, options?: SaveDraftOptions): Promise<SavedDraft>;
   /**

package/core/workflow/definitions_module/services/WorkflowDefinitions.service.ts

@@ -8,6 +8,8 @@ import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowAuditOptions, typ
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import { WorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "../../contracts/WorkflowExtensions";
+import { WorkflowPartitions } from "../../contracts/WorkflowPartitions";
+import { WorkflowProcessUsage } from "../../contracts/WorkflowProcessUsage";
 import { canonicalJson } from "../../internal/canonicalJson";
 import type { WorkflowEvents } from "../../internal/WorkflowEvents";
 import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
@@ -83,6 +85,15 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return row?.folder ?? null;
   }
 
+  async partitionsOf(key: string): Promise<readonly (string | null)[]> {
+    const partitions = await this.partitions(key, null);
+    return partitions.filter((item) => item.enabled).map((item) => item.partition);
+  }
+
+  private async partitions(key: string, actor: WorkflowActor | null) {
+    return await this.services.resolve(WorkflowPartitions).of(key, { partition: null, language: this.languages.default, actor });
+  }
+
   async validate(document: unknown, options: ValidateOptions = {}): Promise<readonly ProcessIssue[]> {
     const port = this.services.resolve(WorkflowExtensions);
     const namespaces = new Set(port.namespaces());
@@ -153,6 +164,19 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return this.detailsOf(row);
   }
 
+  async remove(key: string, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<void> {
+    const row = await this.process(key, false);
+    this.assertNotCode(key);
+    if (row.archivedAt === null) throw new WorkflowError("wrong_status", `Process ${key} is not archived`);
+    // An archived process starts nothing more, so what is counted here cannot grow.
+    const connected = (await this.partitions(key, actor)).filter((item) => item.partition !== null).map((item) => item.partition);
+    if (connected.length > 0) throw new WorkflowError("in_use", `Process ${key} is connected to partitions: ${connected.join(", ")}`);
+    const live = await this.services.tryResolve(WorkflowProcessUsage)?.liveInstances(key) ?? 0;
+    if (live > 0) throw new WorkflowError("in_use", `Process ${key} has ${live} unfinished instances`);
+    await this.db.processes.asNoTracking().where((p) => p.key.eq(key)).executeDelete();
+    await this.changed("deleted", key, actor, options);
+  }
+
   async saveDraft(key: string, document: unknown, actor: WorkflowActor, options: SaveDraftOptions = {}): Promise<SavedDraft> {
     const issues = await this.validate(document, { actor, ...(options.language === undefined ? {} : { language: options.language }) });
     if (issues.some((issue) => issue.code === "too_large")) throw new WorkflowError("invalid_document", "The document is too large", issues);

package/core/workflow/generated/deps.ts

@@ -8,6 +8,7 @@ import { WorkflowClock } from "../contracts/WorkflowClock";
 import { FolderReferences } from "../definitions_module/access/Folder.references";
 import { ProcessReferences } from "../definitions_module/access/Process.references";
 import { ProcessFolderLookup } from "../definitions_module/access/ProcessFolder.lookup";
+import { ProcessPartitionLookup } from "../definitions_module/access/ProcessPartition.lookup";
 import { CatalogImport } from "../definitions_module/code/CatalogImport";
 import { CodeProcessCatalog } from "../definitions_module/code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "../definitions_module/code/CodeProcessPublisher";
@@ -23,8 +24,10 @@ import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
 import { EventsController } from "../runtime_module/http/Events.controller";
 import { InstancesController } from "../runtime_module/http/Instances.controller";
 import { ChildCalls } from "../runtime_module/internal/ChildCalls";
+import { EventDelivery } from "../runtime_module/internal/EventDelivery";
 import { GraphCache } from "../runtime_module/internal/GraphCache";
 import { RunLimits } from "../runtime_module/internal/RunLimits";
+import { RuntimeProcessUsage } from "../runtime_module/internal/RuntimeProcessUsage";
 import { Schedules } from "../runtime_module/internal/Schedules";
 import { TimerStep } from "../runtime_module/internal/TimerStep";
 import { ToolStep } from "../runtime_module/internal/ToolStep";
@@ -44,15 +47,18 @@ registerFrameworkClassDeps([
   [CodeProcessCatalog, [ServiceProvider]],
   [CodeProcessPublisher, [ServiceProvider]],
   [DefinitionsDbContext, [DbContextOptions]],
+  [EventDelivery, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, WorkflowLanguages, ServiceProvider]],
   [EventsController, [IWorkflowRuntime]],
   [FolderReferences, [DefinitionsDbContext]],
   [InstancesController, [IWorkflowRuntime, IWorkflowDefinitions]],
   [ProcessesController, [IWorkflowDefinitions]],
   [ProcessFolderLookup, [DefinitionsDbContext]],
+  [ProcessPartitionLookup, [DefinitionsDbContext, WorkflowLanguages, ServiceProvider]],
   [ProcessReferences, [DefinitionsDbContext]],
   [RunLimits, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions]],
   [RuntimeDbContext, [DbContextOptions]],
-  [Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions]],
+  [RuntimeProcessUsage, [RuntimeDbContext]],
+  [Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, WorkflowLanguages, ServiceProvider]],
   [TaskEvents, [TasksDbContext]],
   [TasksController, [IWorkflowTasks]],
   [TasksDbContext, [DbContextOptions]],
@@ -63,7 +69,7 @@ registerFrameworkClassDeps([
   [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
   [WorkflowLanguages, ["Config:workflow"]],
   [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
-  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider, WorkflowLanguages]],
+  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, EventDelivery, IWorkflowDefinitions, ServiceProvider, WorkflowLanguages]],
   [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock, WorkflowEvents]],
   [WorkflowTools, [ServiceProvider]],
   [WorkflowWorker, [ServiceProvider, "Config:workflow"]],

package/core/workflow/index.ts

@@ -33,6 +33,7 @@ export {
 export {
   IWorkflowRuntime,
   type CancelInstance,
+  type EmitCause,
   type EmitOptions,
   type EmitResult,
   type HistoryEntry,
@@ -41,6 +42,9 @@ export {
   type InstanceSummary,
   type RetryInstance,
   type StartInstance,
+  type StartMany,
+  type StartManyItem,
+  type StartManyResult,
   type TokenDetails,
 } from "./runtime_module/services/IWorkflowRuntime.service";
 export {
@@ -65,6 +69,7 @@ export type { InstanceStatus, StartedVia } from "./runtime_module/model/WfInstan
 export type { TokenStatus } from "./runtime_module/model/WfToken.model";
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
 export { WorkflowExtensions, DefaultWorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "./contracts/WorkflowExtensions";
+export { WorkflowPartitions, DefaultWorkflowPartitions, type ProcessPartition } from "./contracts/WorkflowPartitions";
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
 export type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging, WorkflowRequest, WorkflowToolMetadata } from "./contracts/types";
 

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

@@ -1,6 +1,7 @@
 import { AccessModule } from "../../access";
 import { Module, scoped, singleton } from "../../di";
 import { DefaultWorkflowInputValidator, WorkflowInputValidator } from "../contracts/WorkflowInputValidator";
+import { WorkflowProcessUsage } from "../contracts/WorkflowProcessUsage";
 import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
 import { runtimePermissions } from "./access/Runtime.permissions";
 import { WorkflowRetention } from "./background/WorkflowRetention";
@@ -8,8 +9,10 @@ import { WorkflowWorker } from "./background/WorkflowWorker";
 import { EventsController } from "./http/Events.controller";
 import { InstancesController } from "./http/Instances.controller";
 import { ChildCalls } from "./internal/ChildCalls";
+import { EventDelivery } from "./internal/EventDelivery";
 import { GraphCache } from "./internal/GraphCache";
 import { RunLimits } from "./internal/RunLimits";
+import { RuntimeProcessUsage } from "./internal/RuntimeProcessUsage";
 import { Schedules } from "./internal/Schedules";
 import { TimerStep } from "./internal/TimerStep";
 import { ToolStep } from "./internal/ToolStep";
@@ -35,6 +38,8 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
     scoped(Schedules),
     scoped(ChildCalls),
     scoped(RunLimits),
+    scoped(EventDelivery),
+    scoped(WorkflowProcessUsage, RuntimeProcessUsage),
     singleton(WorkflowInputValidator, DefaultWorkflowInputValidator),
     scoped(IWorkflowRuntime, WorkflowRuntime),
   ],

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

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+import { durationMs, evaluateExpression, inputSpecOf, isTruthy, type Expr, type FormIssue, type InstanceData, type ProcessNode } from "../../../../library/workflow";
+import { LOGGER } from "../../../kernel";
+import type { ServiceProvider } from "../../../di";
+import { isUuid, type WorkflowActor, type WorkflowRequest } from "../../contracts/types";
+import { WorkflowError } from "../../contracts/WorkflowError";
+import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
+import { WorkflowPartitions } from "../../contracts/WorkflowPartitions";
+import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import { canonicalJson } from "../../internal/canonicalJson";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { RuntimeDbContext } from "../model/Runtime.dbContext";
+import { WfJob } from "../model/WfJob.model";
+import type { EmitCause, EmitResult } from "../services/IWorkflowRuntime.service";
+import type { WorkflowEngine } from "./WorkflowEngine";
+
+/** An event on its way: what `emit` got, with the defaults in place. */
+export interface EventMessage {
+  readonly eventKey: string;
+  readonly payload: Record<string, unknown>;
+  readonly correlation: string | null;
+  readonly partition: string | null;
+  readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest | null;
+  readonly cause: EmitCause | null;
+}
+
+interface EventStartConfig {
+  readonly filter?: Expr;
+  readonly debounce?: { readonly key: Expr; readonly window: string };
+  readonly delay?: string;
+  readonly ignoreOwn?: boolean;
+}
+
+/** A process the event is to start, with its checked input. */
+interface PlannedStart {
+  readonly version: VersionDetails;
+  readonly nodeId: string;
+  readonly config: EventStartConfig;
+  readonly input: Record<string, unknown>;
+}
+
+/**
+ * Takes an event to whoever waits for it and to the processes it starts
+ * (WORKFLOW-002 §5.1, §5.2). An `event` job (`emitLater`) turns into an
+ * `eventStart` job per process in one transaction, and each of those starts its
+ * instance in one transaction with its own removal: a repeat after a crash starts
+ * nothing twice. Waits are safe as they are: a subscription leaves with its step.
+ */
+export class EventDelivery {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+    private readonly definitions: IWorkflowDefinitions,
+    private readonly languages: WorkflowLanguages,
+    /** The scope: the application's own ports replace the defaults. */
+    private readonly services: ServiceProvider,
+  ) {}
+
+  /** Moves the waits and starts the processes, now or, under `debounce` and `delay`, by a job. */
+  async emit(message: EventMessage): Promise<EmitResult> {
+    const continued = await this.continueWaits(message);
+    const { planned, rejected } = await this.plan(message);
+    const started: string[] = [];
+    const skipped: { processKey: string; instanceId: string }[] = [];
+    const deferred: { processKey: string }[] = [];
+    for (const start of planned) {
+      if (start.config.debounce !== undefined || start.config.delay !== undefined) {
+        await this.defer(start, message);
+        deferred.push({ processKey: start.version.key });
+        continue;
+      }
+      const begun = await this.begin(start.version, start.nodeId, start.input, message);
+      if (begun.skipped) skipped.push({ processKey: start.version.key, instanceId: begun.id });
+      else started.push(begun.id);
+    }
+    return { started, skipped, deferred, continued, rejected };
+  }
+
+  /** An `event` job: the waits move, and the job becomes an `eventStart` job per process it starts. */
+  async deliverLater(job: WfJob): Promise<void> {
+    const message = job.payload as EventMessage;
+    await this.continueWaits(message);
+    const { planned, rejected } = await this.plan(message);
+    for (const { processKey, issues } of rejected) this.services.tryResolve(LOGGER)?.warn("workflow event did not start a process", { event: message.eventKey, processKey, issues });
+    await this.db.transactionScope(async () => {
+      await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+      for (const start of planned) await this.defer(start, message);
+    });
+  }
+
+  /** An `eventStart` job: its instance starts together with the removal of the job. An archived process takes nothing. */
+  async startLater(job: WfJob): Promise<void> {
+    const { message, input } = job.payload as { readonly message: EventMessage; readonly input: Record<string, unknown> };
+    const version = job.versionId === null ? undefined : await this.definitions.versionById(job.versionId);
+    if (version === undefined || job.nodeId === null || !await this.available(version.key)) {
+      await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+      return;
+    }
+    const graph = this.engine.cache(version);
+    await this.db.transactionScope(async () => {
+      await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+      await this.engine.begin(graph, job.nodeId!, this.beginOptions(input, message));
+    });
+  }
+
+  private async available(processKey: string): Promise<boolean> {
+    try {
+      await this.definitions.latest(processKey);
+      return true;
+    } catch (error) {
+      if (error instanceof WorkflowError) return false;
+      throw error;
+    }
+  }
+
+  /** Every wait of the event: `eventWait.until` may leave a step waiting. */
+  private async continueWaits(message: EventMessage): Promise<string[]> {
+    const { eventKey, correlation, partition, payload } = message;
+    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) => {
+        if (!this.engine.eventAccepted(step, wait.tokenId, payload)) return false;
+        await this.db.subscriptions.asNoTracking().where((s) => s.id.eq(wait.id)).executeDelete();
+        return await this.engine.eventReceived(step, wait.tokenId, eventKey, payload);
+      });
+      if (moved === true) continued.add(wait.instanceId);
+    }
+    return [...continued];
+  }
+
+  /** The `eventStart` nodes that take the event: connected to its partition, past `ignoreOwn` and `filter`, with a valid input. */
+  private async plan(message: EventMessage): Promise<{ readonly planned: PlannedStart[]; readonly rejected: { processKey: string; issues: readonly FormIssue[] }[] }> {
+    const { eventKey, payload, partition, actor } = message;
+    const planned: PlannedStart[] = [];
+    const rejected: { processKey: string; issues: readonly FormIssue[] }[] = [];
+    const data = eventData(message, this.engine.now());
+    const own = await this.causeProcess(message.cause);
+    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;
+        const config = eventStartConfig(node);
+        if (!await this.connected(version.key, partition)) continue;
+        if (config.ignoreOwn === true && own === version.key) continue;
+        if (config.filter !== undefined && !isTruthy(evaluateExpression(config.filter, data))) 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.services.resolve(WorkflowInputValidator).validate(inputSpecOf(version.document), payload, { 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 });
+        else planned.push({ version, nodeId, config, input: value });
+      }
+    }
+    return { planned, rejected };
+  }
+
+  /** Whether the process works in the partition of the event; an event without a partition is for processes without them. */
+  private async connected(processKey: string, partition: string | null): Promise<boolean> {
+    const partitions = await this.services.resolve(WorkflowPartitions).of(processKey, { partition, language: this.languages.default, actor: null });
+    return partitions.some((item) => item.enabled && item.partition === partition);
+  }
+
+  /** The process of the instance that caused the event. */
+  private async causeProcess(cause: EmitCause | null): Promise<string | undefined> {
+    const id = cause?.instanceId;
+    if (!isUuid(id)) return undefined;
+    const row = await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(id));
+    return row?.processKey;
+  }
+
+  private async begin(version: VersionDetails, nodeId: string, input: Record<string, unknown>, message: EventMessage) {
+    return await this.engine.begin(this.engine.cache(version), nodeId, this.beginOptions(input, message));
+  }
+
+  private beginOptions(input: Record<string, unknown>, message: EventMessage) {
+    return {
+      input,
+      partition: message.partition,
+      businessKey: message.correlation,
+      startedVia: "event" as const,
+      actor: message.actor,
+      request: message.request,
+      event: { key: message.eventKey, payload: message.payload },
+      ...(message.cause === null ? {} : { cause: message.cause }),
+    };
+  }
+
+  /**
+   * An `eventStart` job due after `delay` and the `debounce` window. The window runs
+   * from its first event and later ones replace what the job carries, so a steady
+   * stream of events still starts a process once per window. A job a worker holds
+   * takes no more events: the next one opens a new window.
+   */
+  private async defer(start: PlannedStart, message: EventMessage): Promise<void> {
+    const { version, nodeId, config, input } = start;
+    const now = this.engine.now();
+    const dueAt = new Date(now.getTime() + (config.debounce === undefined ? 0 : durationMs(config.debounce.window) ?? 0) + (config.delay === undefined ? 0 : durationMs(config.delay) ?? 0));
+    const payload = { message, input };
+    const dedupeKey = config.debounce === undefined ? null : debounceKey(version.key, nodeId, message, config.debounce.key, now);
+    const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "eventStart" as const, versionId: version.id, nodeId, partition: message.partition, dueAt, payload, dedupeKey, createdAt: now });
+    if (dedupeKey === null) {
+      await this.db.jobs.insertIfAbsent(job, { conflictBy: (j) => [j.id] });
+      return;
+    }
+    await this.db.transactionScope(async () => {
+      await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext({0}))", dedupeKey);
+      const merged = await this.db.jobs.asNoTracking().where((j) => j.dedupeKey.eq(dedupeKey).and(j.lockedUntil.isNull())).executeUpdate({ payload, versionId: version.id });
+      if (merged.affectedRows === 0) await this.db.jobs.insertIfAbsent(job, { conflictBy: (j) => [j.id] });
+    });
+  }
+}
+
+function eventStartConfig(node: ProcessNode): EventStartConfig {
+  return (node.config ?? {}) as unknown as EventStartConfig;
+}
+
+/** What the expressions of an `eventStart` read: there is no instance yet. */
+function eventData(message: EventMessage, now: Date): InstanceData {
+  return {
+    input: {},
+    vars: {},
+    nodes: {},
+    event: message.payload,
+    trigger: { via: "event", at: now.toISOString(), actor: message.actor, eventKey: message.eventKey, ...(message.cause === null ? {} : { cause: message.cause }) },
+    now: now.toISOString(),
+  };
+}
+
+function debounceKey(processKey: string, nodeId: string, message: EventMessage, key: Expr, now: Date): string {
+  const value = evaluateExpression(key, eventData(message, now)) ?? null;
+  return createHash("sha256").update(canonicalJson([processKey, nodeId, message.partition, value])).digest("hex");
+}