bazis 0.125.0 → 0.127.0

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.125.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.127.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/workflow/Workflow.module.ts

@@ -3,13 +3,15 @@ import { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefiniti
 import { IWorkflowDefinitions } from "./definitions_module/services/IWorkflowDefinitions.service";
 import { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
 import { IWorkflowRuntime } from "./runtime_module/services/IWorkflowRuntime.service";
+import { WorkflowTasksModule } from "./tasks_module/WorkflowTasks.module";
+import { IWorkflowTasks } from "./tasks_module/services/IWorkflowTasks.service";
 
 /**
  * Business processes (WORKFLOW-001): the pack only assembles its parts
  * ([passport](MODULE.md)). An application imports it, or only the parts it needs.
  */
 @Module({
-  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule],
-  exports: [IWorkflowDefinitions, IWorkflowRuntime],
+  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule, WorkflowTasksModule],
+  exports: [IWorkflowDefinitions, IWorkflowRuntime, IWorkflowTasks],
 })
 export class WorkflowModule {}

package/core/workflow/definitions_module/model/WfVersion.model.ts

@@ -9,7 +9,8 @@ export class WfVersion {
   @UUID({ version: "v7" })
   id = "";
 
-  @Column({ type: "uuid" })
+  /** A reference: the foreign key makes the column a native uuid. A non-key `type: "uuid"` would generate a value. */
+  @Column({ type: "text" })
   processId = "";
 
   @Column({ type: "integer" })

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

@@ -70,6 +70,8 @@ export abstract class IWorkflowDefinitions {
   abstract version(key: string, version: number): Promise<VersionDetails>;
   /** The latest published version of a process that is not archived. */
   abstract latest(key: string): Promise<VersionDetails>;
+  /** The latest version of every process that is not archived: where event and scheduled starts come from. */
+  abstract published(): Promise<readonly VersionDetails[]>;
   /** A version by id, for the engine; `undefined` if there is none. */
   abstract versionById(id: string): Promise<VersionDetails | undefined>;
   /** Processes with a retention period: what the retention service deletes. */

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

@@ -141,6 +141,16 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return await this.version(key, row.latestVersion);
   }
 
+  async published(): Promise<readonly VersionDetails[]> {
+    const processes = await this.db.processes.asNoTracking().where((p) => p.archivedAt.isNull().and(p.latestVersion.isNotNull())).toList();
+    if (processes.length === 0) return [];
+    const byId = new Map(processes.map((process) => [process.id, process]));
+    const versions = await this.db.versions.asNoTracking().where((v) => v.processId.in([...byId.keys()])).toList();
+    return versions
+      .filter((version) => byId.get(version.processId)?.latestVersion === version.version)
+      .map((version) => versionOf(byId.get(version.processId)!.key, version));
+  }
+
   async versionById(id: string): Promise<VersionDetails | undefined> {
     if (!isUuid(id)) return undefined;
     const version = await this.db.versions.asNoTracking().firstOrDefault((v) => v.id.eq(id));

package/core/workflow/index.ts

@@ -6,6 +6,9 @@
 export { WorkflowModule } from "./Workflow.module";
 export { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefinitions.module";
 export { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
+export { WorkflowTasksModule } from "./tasks_module/WorkflowTasks.module";
+export { IWorkflowTasks, type TaskDetails, type TaskListQuery } from "./tasks_module/services/IWorkflowTasks.service";
+export type { TaskStatus } from "./tasks_module/model/WfTask.model";
 export {
   IWorkflowDefinitions,
   type CreateProcess,
@@ -18,6 +21,8 @@ export {
 } from "./definitions_module/services/IWorkflowDefinitions.service";
 export {
   IWorkflowRuntime,
+  type EmitOptions,
+  type EmitResult,
   type HistoryEntry,
   type InstanceDetails,
   type InstanceListQuery,
@@ -27,9 +32,11 @@ export {
 } from "./runtime_module/services/IWorkflowRuntime.service";
 export {
   WORKFLOW_INSTANCE_FINISHED,
+  WORKFLOW_INSTANCES_DELETED,
   WORKFLOW_TASK_REQUESTED,
   WORKFLOW_TOKEN_CLOSED,
   type WorkflowInstanceFinished,
+  type WorkflowInstancesDeleted,
   type WorkflowTaskRequested,
   type WorkflowTokenClosed,
 } from "./runtime_module/events/Runtime.events";

package/core/workflow/internal/http.ts

@@ -16,6 +16,12 @@ export async function authorize(ctx: HttpContext, action: WorkflowAction, target
   return actor;
 }
 
+/** Whom the caller's tasks are addressed to, from the application's {@link WorkflowAccess}. */
+export async function assigneesOf(ctx: HttpContext, actor: WorkflowActor): Promise<readonly string[]> {
+  const access = ctx.services.tryResolve(WorkflowAccess);
+  return access === undefined ? [] : await access.assignees(ctx, actor);
+}
+
 /** A route parameter as a string. */
 export function param(ctx: HttpContext, name: string): string {
   return String(ctx.params[name] ?? "");

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

@@ -7,8 +7,10 @@ import { WorkflowTools } from "../internal/WorkflowTools";
 import { WorkflowRetention } from "./background/WorkflowRetention";
 import { WorkflowWorker } from "./background/WorkflowWorker";
 import { workflowRuntimeConfig } from "./config/Runtime.config";
+import { EventsController } from "./http/Events.controller";
 import { InstancesController } from "./http/Instances.controller";
 import { GraphCache } from "./internal/GraphCache";
+import { Schedules } from "./internal/Schedules";
 import { TimerStep } from "./internal/TimerStep";
 import { ToolStep } from "./internal/ToolStep";
 import { WorkflowEngine } from "./internal/WorkflowEngine";
@@ -37,6 +39,7 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
     ))),
     scoped(ToolStep, ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools] as const),
     scoped(TimerStep, TimerStep, [RuntimeDbContext, WorkflowEngine] as const),
+    scoped(Schedules, Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions] as const),
     // The application's input validator, if it registered one anywhere; the built-in one otherwise.
     DI.scoped(DI.factoryProviderWithResolver(IWorkflowRuntime, [], (resolver) => new WorkflowRuntime(
       resolver.resolve(RuntimeDbContext),
@@ -45,7 +48,7 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
       resolver.resolve(SERVICE_PROVIDER).tryResolve(WorkflowInputValidator) ?? new DefaultWorkflowInputValidator(),
     ))),
   ],
-  controllers: [DI.bindDeps(InstancesController, IWorkflowRuntime)],
+  controllers: [DI.bindDeps(InstancesController, IWorkflowRuntime), DI.bindDeps(EventsController, IWorkflowRuntime)],
   background: [
     DI.bindDeps(WorkflowWorker, SERVICE_PROVIDER, workflowRuntimeConfig.token),
     DI.bindDeps(WorkflowRetention, SERVICE_PROVIDER, workflowRuntimeConfig.token),

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

@@ -1,7 +1,8 @@
 import { BackgroundService, delay } from "../../../background";
 import type { ServiceProvider } from "../../../di";
-import type { ConfigView } from "../../../kernel";
+import { EventBus, type ConfigView } from "../../../kernel";
 import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import { WORKFLOW_INSTANCES_DELETED } from "../events/Runtime.events";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WorkflowSettings } from "./WorkflowWorker";
 
@@ -11,6 +12,8 @@ const DAY_MS = 86_400_000;
  * Deletes `completed` and `cancelled` instances older than their process's
  * `retentionDays`, with tokens, jobs, subscriptions and history (by cascade),
  * `retention.batchSize` at a time. `failed` instances wait for a person and stay.
+ * Each deleted batch is published as `WORKFLOW_INSTANCES_DELETED`, so parts
+ * with their own data (tasks) drop theirs.
  */
 export class WorkflowRetention extends BackgroundService {
   constructor(
@@ -55,6 +58,7 @@ export class WorkflowRetention extends BackgroundService {
           if (ids.length === 0) break;
           await db.instances.asNoTracking().where((i) => i.id.in(ids)).executeDelete();
           deleted += ids.length;
+          await scope.resolve(EventBus).publishScoped(scope, WORKFLOW_INSTANCES_DELETED, { instanceIds: ids });
           if (ids.length < batchSize) break;
         }
       }

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

@@ -2,6 +2,7 @@ import { BackgroundService, delay } from "../../../background";
 import type { ServiceProvider } from "../../../di";
 import type { ConfigView } from "../../../kernel";
 import type { workflowRuntimeConfig } from "../config/Runtime.config";
+import { Schedules } from "../internal/Schedules";
 import { TimerStep } from "../internal/TimerStep";
 import { ToolStep } from "../internal/ToolStep";
 import { WorkflowEngine } from "../internal/WorkflowEngine";
@@ -12,6 +13,8 @@ import type { WfJob } from "../model/WfJob.model";
 const LEASE_MS = 5 * 60_000;
 /** A job that keeps failing outside its Tool (the database, a lost version) fails its step after this many tries. */
 const MAX_JOB_ATTEMPTS = 5;
+/** How often the scheduled starts are matched against the published versions. */
+const RECONCILE_MS = 60_000;
 
 
 /**
@@ -32,7 +35,12 @@ export class WorkflowWorker extends BackgroundService {
     if (!this.config.get("worker.enabled")) return;
     const intervalMs = this.config.get("worker.intervalMs");
     const batchSize = this.config.get("worker.batchSize");
+    let reconciledAt = 0;
     while (!signal.aborted) {
+      if (Date.now() - reconciledAt >= RECONCILE_MS) {
+        reconciledAt = Date.now();
+        await this.reconcile();
+      }
       let claimed = 0;
       try {
         const jobs = await this.claim(batchSize);
@@ -53,6 +61,7 @@ export class WorkflowWorker extends BackgroundService {
     const scope = this.services.createScope();
     try {
       if (job.kind === "timer") await scope.resolve(TimerStep).run(job);
+      else if (job.kind === "schedule") await scope.resolve(Schedules).fire(job);
       else await scope.resolve(ToolStep).run(job, signal);
     } catch (error) {
       this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId, attempts: job.attempts });
@@ -62,6 +71,17 @@ export class WorkflowWorker extends BackgroundService {
     }
   }
 
+  private async reconcile(): Promise<void> {
+    const scope = this.services.createScope();
+    try {
+      await scope.resolve(Schedules).reconcile();
+    } catch (error) {
+      this.reportFailure("scheduled starts could not be planned", error);
+    } finally {
+      await scope.dispose();
+    }
+  }
+
   /** A job that failed outside its Tool waits a minute per try, then fails its step for a person to retry. */
   private async giveUpOrDelay(job: WfJob, error: unknown): Promise<void> {
     const message = error instanceof Error ? error.message : String(error);
@@ -90,7 +110,7 @@ export class WorkflowWorker extends BackgroundService {
       return await db.transactionScope(async () => {
         const now = new Date();
         const jobs = await db.jobs
-          .where((j) => j.kind.in(["tool", "timer"]).and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
+          .where((j) => j.kind.in(["tool", "timer", "schedule"]).and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
           .orderBy((j) => j.id)
           .take(batchSize)
           .forUpdate({ skipLocked: true })

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

@@ -32,6 +32,12 @@ export interface WorkflowInstanceFinished {
   readonly status: Extract<InstanceStatus, "completed" | "cancelled">;
 }
 
+/** Retention deleted these finished instances with their tokens and history. */
+export interface WorkflowInstancesDeleted {
+  readonly instanceIds: readonly string[];
+}
+
 export const WORKFLOW_TASK_REQUESTED = createEventToken<WorkflowTaskRequested>("workflow.task-requested");
 export const WORKFLOW_TOKEN_CLOSED = createEventToken<WorkflowTokenClosed>("workflow.token-closed");
 export const WORKFLOW_INSTANCE_FINISHED = createEventToken<WorkflowInstanceFinished>("workflow.instance-finished");
+export const WORKFLOW_INSTANCES_DELETED = createEventToken<WorkflowInstancesDeleted>("workflow.instances-deleted");

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

@@ -0,0 +1,26 @@
+import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
+import { Controller, Post, type HttpContext } from "../../../http";
+import { authorize, body, optionalString, param } from "../../internal/http";
+import { IWorkflowRuntime } from "../services/IWorkflowRuntime.service";
+
+/** Events from outside — a webhook, another service — over HTTP (WORKFLOW-001 §4). */
+@Controller("workflow/events")
+export class EventsController {
+  constructor(private readonly runtime: IWorkflowRuntime) {}
+
+  @Post(":eventKey")
+  async emit(ctx: HttpContext) {
+    const eventKey = param(ctx, "eventKey");
+    const request = await body(ctx);
+    const partition = optionalString(request.partition, "partition") ?? null;
+    const actor = await authorize(ctx, "events.emit", { partition });
+    const result = await this.runtime.emit(eventKey, request.payload ?? {}, {
+      correlation: optionalString(request.correlation, "correlation") ?? null,
+      partition,
+      actor,
+    });
+    ctx.res.status(202);
+    return result;
+  }
+}
+contextOnlyController(EventsController);

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

@@ -0,0 +1,82 @@
+import { parseCron } from "../../../../library/workflow";
+import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
+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;
+
+/**
+ * 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.
+ */
+export class Schedules {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+    private readonly definitions: IWorkflowDefinitions,
+  ) {}
+
+  /** Adds jobs for new scheduled versions and drops those of replaced or archived ones. */
+  async reconcile(now = new Date()): 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 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);
+      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);
+        if (dueAt === undefined) continue;
+        const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "schedule" as const, versionId: version.id, dueAt });
+        this.db.jobs.add(job);
+        added.push(job);
+      }
+      await this.db.saveChanges();
+    });
+    // The jobs belong to the worker from now on: this context must not hold them.
+    for (const job of added) this.db.detach(job);
+  }
+
+  /** A `schedule` job is due: start an instance from every node firing at this minute 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) {
+      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 graph = this.engine.cache(latest);
+    await this.db.transactionScope(async () => {
+      const next = nextFiring(latest, due);
+      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: {}, partition: null, businessKey: null, startedVia: "schedule", actor: SCHEDULE_ACTOR });
+      }
+    });
+  }
+}
+
+function scheduleNodes(version: VersionDetails) {
+  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];
+  });
+}
+
+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));
+}

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

@@ -8,6 +8,7 @@ import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import { WfHistory, type HistoryType } from "../model/WfHistory.model";
 import { WfInstance, type StartedVia } from "../model/WfInstance.model";
 import { WfJob } from "../model/WfJob.model";
+import { WfSubscription } from "../model/WfSubscription.model";
 import { WfToken } from "../model/WfToken.model";
 import { buildGraph, type GraphCache, type ProcessGraph } from "./GraphCache";
 
@@ -36,8 +37,6 @@ export interface BeginOptions {
   readonly actor: WorkflowActor;
 }
 
-/** Node kinds that come with later stages: an instance reaching one fails with a clear reason. */
-const NOT_YET = new Set(["eventWait"]);
 const LIVE = new Set(["active", "waiting", "failed"]);
 
 /**
@@ -174,9 +173,32 @@ export class WorkflowEngine {
       this.history(step, token, token.nodeId, "timer", { firedAt });
       return await this.complete(step, tokenId, { firedAt });
     }
-    if (node?.kind !== "boundaryTimer" || node.attachedTo === undefined) return false;
+    if (node?.kind !== "boundaryTimer") return false;
+    return await this.fireBoundary(step, token, node, { firedAt }, "timer");
+  }
+
+  /**
+   * An event the token waits for arrived. An `eventWait` step moves on with
+   * the payload (and `saveTo`); a `boundaryEvent` takes its flow like a
+   * boundary timer. `false` when the token no longer waits.
+   */
+  async eventReceived(step: Step, tokenId: string, eventKey: string, payload: Record<string, unknown>): Promise<boolean> {
+    const token = step.tokens.find((t) => t.id === tokenId);
+    if (!token || token.status !== "waiting" || step.instance.status !== "running") return false;
+    const node = step.graph.document.nodes[token.nodeId];
+    if (node?.kind === "eventWait") {
+      this.history(step, token, token.nodeId, "event", { event: eventKey });
+      return await this.complete(step, tokenId, payload);
+    }
+    if (node?.kind !== "boundaryEvent") return false;
+    return await this.fireBoundary(step, token, node, payload, "event", { event: eventKey });
+  }
+
+  /** A boundary timer or event fired: an interrupting one closes the watched step first, then the boundary takes its flow. */
+  private async fireBoundary(step: Step, token: WfToken, node: ProcessNode, output: Record<string, unknown>, type: "timer" | "event", details: Record<string, unknown> = {}): Promise<boolean> {
+    if (node.attachedTo === undefined) return false;
     const interrupting = node.config?.interrupting !== false;
-    this.history(step, token, token.nodeId, "timer", { firedAt, interrupting });
+    this.history(step, token, token.nodeId, type, { ...details, ...(type === "timer" ? output : {}), interrupting });
     if (interrupting) {
       for (const host of step.tokens.filter((t) => t.nodeId === node.attachedTo && LIVE.has(t.status))) {
         this.close(host, "cancelled");
@@ -186,7 +208,7 @@ export class WorkflowEngine {
       }
       this.disarm(step, node.attachedTo, token.id);
     }
-    step.instance.nodes = { ...step.instance.nodes, [token.nodeId]: { firedAt } };
+    step.instance.nodes = { ...step.instance.nodes, [token.nodeId]: output };
     await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
     return true;
   }
@@ -277,10 +299,6 @@ export class WorkflowEngine {
     }
     // An error boundary that caught a step's failure: it only leads on.
     if (role === "boundary") return this.leave(step, token, this.single(step, token.nodeId));
-    if (NOT_YET.has(node.kind)) {
-      this.fail(step, token, "not_supported", `${node.kind} steps are not supported yet`);
-      return [];
-    }
     switch (node.kind) {
       case "serviceTask":
         return this.arm(step, token, this.waitForTool(step, token));
@@ -288,6 +306,8 @@ export class WorkflowEngine {
         return this.arm(step, token, this.waitForTask(step, token, node));
       case "timerCatch":
         return this.arm(step, token, this.waitForTimer(step, token, node));
+      case "eventWait":
+        return this.arm(step, token, this.waitForEvent(step, token, node));
       case "exclusiveGateway":
         return this.choose(step, token);
       case "parallelGateway":
@@ -316,6 +336,17 @@ export class WorkflowEngine {
   private arm(step: Step, host: WfToken, next: WfToken[]): WfToken[] {
     if (host.status !== "waiting") return next;
     for (const [id, node] of step.graph.boundaries.get(host.nodeId) ?? []) {
+      if (node.kind === "boundaryEvent") {
+        const correlation = correlationOf(node.config ?? {}, dataOf(step.instance));
+        if (correlation === undefined) {
+          this.fail(step, host, "bad_correlation", `the correlation of ${id} has no value`);
+          return [];
+        }
+        const watcher = this.spawn(step, id, null);
+        watcher.status = "waiting";
+        this.subscribe(step, watcher, String(node.config?.event), correlation);
+        continue;
+      }
       if (node.kind !== "boundaryTimer") continue;
       const dueAt = timerDue(node.config ?? {}, dataOf(step.instance));
       if (dueAt === undefined) {
@@ -338,6 +369,28 @@ export class WorkflowEngine {
     }
   }
 
+  private waitForEvent(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
+    const correlation = correlationOf(node.config ?? {}, dataOf(step.instance));
+    if (correlation === undefined) {
+      this.fail(step, token, "bad_correlation", `the correlation of ${token.nodeId} has no value`);
+      return [];
+    }
+    token.status = "waiting";
+    this.subscribe(step, token, String(node.config?.event), correlation);
+    return [];
+  }
+
+  private subscribe(step: Step, token: WfToken, eventKey: string, correlation: string | null): void {
+    this.db.subscriptions.add(Object.assign(new WfSubscription(), {
+      id: Bun.randomUUIDv7(),
+      instanceId: step.instance.id,
+      tokenId: token.id,
+      eventKey,
+      correlation,
+      partition: step.instance.partition,
+    }));
+  }
+
   private waitForTool(step: Step, token: WfToken): WfToken[] {
     token.status = "waiting";
     this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "tool" as const, instanceId: step.instance.id, tokenId: token.id, dueAt: new Date() }));
@@ -465,6 +518,17 @@ export function timerDue(config: Readonly<Record<string, unknown>>, data: Instan
   return undefined;
 }
 
+/**
+ * The correlation a wait matches: the value at `config.correlation` as a
+ * string, `null` without a path (any event of the key), `undefined` when the
+ * path has no value.
+ */
+export function correlationOf(config: Readonly<Record<string, unknown>>, data: InstanceData): string | null | undefined {
+  if (typeof config.correlation !== "string") return null;
+  const value = readPath(data, config.correlation);
+  return value === undefined || value === null || value === "" || typeof value === "object" ? undefined : String(value);
+}
+
 export function dataOf(instance: WfInstance): InstanceData {
   return { input: instance.input, vars: instance.vars, nodes: instance.nodes };
 }

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

@@ -11,10 +11,10 @@ export class WfHistory {
   @UUID({ version: "v7" })
   id = "";
 
-  @Column({ type: "uuid" })
+  @Column({ type: "text" })
   instanceId = "";
 
-  @Column({ type: "uuid", nullable: true })
+  @Column({ type: "text", nullable: true })
   tokenId: string | null = null;
 
   @Column({ type: "text", nullable: true })

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

@@ -19,7 +19,7 @@ export class WfInstance {
   id = "";
 
   /** The version (a Definitions row: a reference without a foreign key). */
-  @Column({ type: "uuid" })
+  @Column({ type: "text" })
   versionId = "";
 
   @Column({ type: "text" })

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

@@ -19,15 +19,15 @@ export class WfJob {
 
   /** `null` for a `schedule` job: its instance does not exist yet. */
   @Index()
-  @Column({ type: "uuid", nullable: true })
+  @Column({ type: "text", nullable: true })
   instanceId: string | null = null;
 
   @Index()
-  @Column({ type: "uuid", nullable: true })
+  @Column({ type: "text", nullable: true })
   tokenId: string | null = null;
 
   /** The version a `schedule` job starts. */
-  @Column({ type: "uuid", nullable: true })
+  @Column({ type: "text", nullable: true })
   versionId: string | null = null;
 
   @Index()

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

@@ -9,11 +9,11 @@ export class WfSubscription {
   @UUID({ version: "v7" })
   id = "";
 
-  @Column({ type: "uuid" })
+  @Column({ type: "text" })
   instanceId = "";
 
   @Index()
-  @Column({ type: "uuid" })
+  @Column({ type: "text" })
   tokenId = "";
 
   @Column({ type: "text" })

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

@@ -15,7 +15,7 @@ export class WfToken {
   @UUID({ version: "v7" })
   id = "";
 
-  @Column({ type: "uuid" })
+  @Column({ type: "text" })
   instanceId = "";
 
   @Column({ type: "text" })

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

@@ -1,3 +1,4 @@
+import type { FormIssue } from "../../../../library/workflow";
 import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { HistoryType } from "../model/WfHistory.model";
 import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
@@ -55,6 +56,24 @@ export interface HistoryEntry {
   readonly at: Date;
 }
 
+export interface EmitOptions {
+  /** 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. */
+  readonly partition?: string | null;
+  /** On whose behalf started instances run; `{ kind: "system", id: "event:<key>" }` by default. */
+  readonly actor?: WorkflowActor;
+}
+
+export interface EmitResult {
+  /** Instances started by an `eventStart`. */
+  readonly started: readonly string[];
+  /** Instances whose `eventWait` or `boundaryEvent` took the event. */
+  readonly continued: readonly string[];
+  /** Processes with an `eventStart` whose input the payload did not pass. */
+  readonly rejected: readonly { readonly processKey: string; readonly issues: readonly FormIssue[] }[];
+}
+
 export interface InstanceListQuery extends WorkflowPaging {
   readonly partition?: string;
   readonly status?: InstanceStatus;
@@ -75,6 +94,11 @@ export abstract class IWorkflowRuntime {
   abstract retry(instanceId: string, options: { readonly actor: WorkflowActor }): Promise<InstanceDetails>;
   /** Finishes a user task's wait with the form output and moves on; `wrong_status` when the token no longer waits. */
   abstract completeToken(tokenId: string, output: unknown, actor: WorkflowActor): Promise<InstanceDetails>;
+  /**
+   * Delivers an event: starts processes whose latest version has an
+   * `eventStart` for the key, and moves the instances waiting for it.
+   */
+  abstract emit(eventKey: string, payload?: unknown, options?: EmitOptions): Promise<EmitResult>;
   /** 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,4 +1,4 @@
-import type { FormSpec } from "../../../../library/workflow";
+import type { FormIssue, FormSpec } from "../../../../library/workflow";
 import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import type { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
@@ -10,6 +10,8 @@ import type { WfInstance } from "../model/WfInstance.model";
 import type { WfToken } from "../model/WfToken.model";
 import {
   IWorkflowRuntime,
+  type EmitOptions,
+  type EmitResult,
   type HistoryEntry,
   type InstanceDetails,
   type InstanceListQuery,
@@ -18,6 +20,7 @@ import {
 } from "./IWorkflowRuntime.service";
 
 const STATUSES = new Set(["running", "completed", "cancelled", "failed"]);
+const EVENT_KEY = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$/;
 
 export class WorkflowRuntime extends IWorkflowRuntime {
   constructor(
@@ -87,6 +90,45 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     return await this.instance(token.instanceId);
   }
 
+  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);
+    }
+
+    const started: 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(version.document.input, data, { purpose: "input", processKey: version.key, partition });
+        const issues = all.filter((issue) => issue.code !== "unknown");
+        if (issues.length > 0) {
+          rejected.push({ processKey: version.key, issues });
+          continue;
+        }
+        started.push(await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor }));
+      }
+    }
+    return { started, continued: [...continued], rejected };
+  }
+
   async instances(query: InstanceListQuery = {}): Promise<WorkflowPage<InstanceSummary>> {
     const { limit, offset } = pagingOf(query);
     if (query.status !== undefined && !STATUSES.has(query.status)) throw new WorkflowError("invalid_input", "status must be running, completed, cancelled or failed");

package/core/workflow/tasks_module/WorkflowTasks.module.ts

@@ -0,0 +1,29 @@
+import { DI, Module, scoped } from "../../di";
+import { withEventSubscribers } from "../../kernel";
+import { IWorkflowRuntime } from "../runtime_module/services/IWorkflowRuntime.service";
+import { WorkflowRuntimeModule } from "../runtime_module/WorkflowRuntime.module";
+import { TaskEvents } from "./events/TaskEvents";
+import { TasksController } from "./http/Tasks.controller";
+import { TasksDbContext, tasksStore } from "./model/Tasks.dbContext";
+import { WfTask } from "./model/WfTask.model";
+import { IWorkflowTasks } from "./services/IWorkflowTasks.service";
+import { WorkflowTasks } from "./services/WorkflowTasks.service";
+
+/**
+ * Tasks for people: the inbox of `userTask` steps ([passport](MODULE.md)).
+ * Dependencies are explicit: the framework's classes are not covered by the
+ * application's codegen.
+ */
+@Module({
+  imports: [WorkflowRuntimeModule],
+  ormBazis: { context: TasksDbContext, entities: [WfTask], ownedStore: tasksStore, registerRepositories: false },
+  providers: [
+    scoped(WorkflowTasks, WorkflowTasks, [TasksDbContext, IWorkflowRuntime] as const),
+    DI.scoped(DI.factoryProviderWithResolver(IWorkflowTasks, [], (resolver) => resolver.resolve(WorkflowTasks))),
+    scoped(TaskEvents, TaskEvents, [WorkflowTasks] as const),
+    ...withEventSubscribers(TaskEvents),
+  ],
+  controllers: [DI.bindDeps(TasksController, IWorkflowTasks)],
+  exports: [IWorkflowTasks],
+})
+export class WorkflowTasksModule {}

package/core/workflow/tasks_module/events/TaskEvents.ts

@@ -0,0 +1,23 @@
+import { OnEvent } from "../../../kernel";
+import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
+import type { WorkflowTasks } from "../services/WorkflowTasks.service";
+
+/** Keeps the inbox in line with the steps: a waiting user task gets a task, a closed one cancels it. */
+export class TaskEvents {
+  constructor(private readonly tasks: WorkflowTasks) {}
+
+  @OnEvent(WORKFLOW_TASK_REQUESTED)
+  requested(event: WorkflowTaskRequested): Promise<void> {
+    return this.tasks.requested(event);
+  }
+
+  @OnEvent(WORKFLOW_TOKEN_CLOSED)
+  closed(event: WorkflowTokenClosed): Promise<void> {
+    return this.tasks.closed(event);
+  }
+
+  @OnEvent(WORKFLOW_INSTANCES_DELETED)
+  deleted(event: WorkflowInstancesDeleted): Promise<void> {
+    return this.tasks.deleted(event);
+  }
+}

package/core/workflow/tasks_module/http/Tasks.controller.ts

@@ -0,0 +1,67 @@
+import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
+import { Controller, Get, Post, type HttpContext } from "../../../http";
+import type { WorkflowActor } from "../../contracts/types";
+import { WorkflowError } from "../../contracts/WorkflowError";
+import { assigneesOf, authorize, body, optionalString, pagingQuery, param } from "../../internal/http";
+import type { TaskStatus } from "../model/WfTask.model";
+import { IWorkflowTasks, type TaskDetails } from "../services/IWorkflowTasks.service";
+
+/**
+ * The caller's tasks (WORKFLOW-001 §5): those addressed to any of
+ * `WorkflowAccess.assignees` or claimed by the caller. Another person's task
+ * answers 404, as if it did not exist.
+ */
+@Controller("workflow/tasks")
+export class TasksController {
+  constructor(private readonly tasks: IWorkflowTasks) {}
+
+  @Get()
+  async list(ctx: HttpContext) {
+    const partition = optionalString(ctx.query("partition"), "partition");
+    const actor = await authorize(ctx, "tasks.work", { partition: partition ?? null });
+    const status = ctx.query("status");
+    const page = await this.tasks.list({
+      ...pagingQuery(ctx),
+      assignees: await assigneesOf(ctx, actor),
+      actor,
+      ...(status === undefined ? {} : { status: status.split(",") as TaskStatus[] }),
+      partition,
+      processKey: optionalString(ctx.query("processKey"), "processKey"),
+    });
+    return { data: page.items, meta: { total: page.total } };
+  }
+
+  @Get(":id")
+  async get(ctx: HttpContext) {
+    return (await this.visible(ctx)).task;
+  }
+
+  @Post(":id/claim")
+  async claim(ctx: HttpContext) {
+    const { task, actor } = await this.visible(ctx);
+    return await this.tasks.claim(task.id, actor);
+  }
+
+  @Post(":id/release")
+  async release(ctx: HttpContext) {
+    const { task, actor } = await this.visible(ctx);
+    return await this.tasks.release(task.id, actor);
+  }
+
+  @Post(":id/complete")
+  async complete(ctx: HttpContext) {
+    const { task, actor } = await this.visible(ctx);
+    const request = await body(ctx);
+    return await this.tasks.complete(task.id, request.output ?? {}, actor);
+  }
+
+  /** The task if the caller may see it: addressed to one of their assignees or claimed by them. */
+  private async visible(ctx: HttpContext): Promise<{ task: TaskDetails; actor: WorkflowActor }> {
+    const task = await this.tasks.get(param(ctx, "id"));
+    const actor = await authorize(ctx, "tasks.work", { processKey: task.processKey, partition: task.partition, instanceId: task.instanceId, taskId: task.id });
+    const assignees = await assigneesOf(ctx, actor);
+    if (!assignees.includes(task.assignee) && task.claimedBy !== actor.id) throw new WorkflowError("not_found", `Task ${task.id} does not exist`);
+    return { task, actor };
+  }
+}
+contextOnlyController(TasksController);

package/core/workflow/tasks_module/model/Tasks.dbContext.ts

@@ -0,0 +1,14 @@
+import { DbContext, defineOrmOwnedStoreV1 } from "../../../orm";
+import { WfTask } from "./WfTask.model";
+
+export class TasksDbContext extends DbContext {
+  readonly tasks = this.set(WfTask);
+}
+
+/** The table of the Tasks part: bazis creates and checks it in the application database. */
+export const tasksStore = defineOrmOwnedStoreV1({
+  contract: "bazis.orm-owned-store/v1",
+  storeKey: "bazis.workflow.tasks",
+  formatVersion: 1,
+  ownedScope: { schema: "public", tablePrefix: "bazis_wf_task_" },
+});

package/core/workflow/tasks_module/model/WfTask.model.ts

@@ -0,0 +1,69 @@
+import { Column, Entity, Index, UUID } from "../../../orm";
+import type { FormSpec } from "../../../../library/workflow";
+
+/** `open` waits for someone, `claimed` is taken by one person, `completed` and `cancelled` are done. */
+export type TaskStatus = "open" | "claimed" | "completed" | "cancelled";
+
+/**
+ * A task for a person: a `userTask` step of an instance waiting for its form.
+ * Created from `WORKFLOW_TASK_REQUESTED`; references are text (other stores).
+ */
+@Index(["assignee", "status"])
+@Index(["partition", "status"])
+@Entity({ table: "bazis_wf_task_items" })
+export class WfTask {
+  @UUID({ version: "v7" })
+  id = "";
+
+  /** The waiting token: one task per token. */
+  @Index({ unique: true })
+  @Column({ type: "text" })
+  tokenId = "";
+
+  @Index()
+  @Column({ type: "text" })
+  instanceId = "";
+
+  @Column({ type: "text" })
+  processKey = "";
+
+  @Column({ type: "text" })
+  nodeId = "";
+
+  @Column({ type: "text", nullable: true })
+  partition: string | null = null;
+
+  @Column({ type: "text" })
+  title = "";
+
+  /** `role:<code>` or `user:<id>`. */
+  @Column({ type: "text" })
+  assignee = "";
+
+  @Column({ type: "json", nullable: true })
+  form: FormSpec | null = null;
+
+  @Column({ type: "datetime", nullable: true })
+  dueAt: Date | null = null;
+
+  @Column({ type: "text" })
+  status: TaskStatus = "open";
+
+  @Column({ type: "text", nullable: true })
+  claimedById: string | null = null;
+
+  @Column({ type: "datetime", nullable: true })
+  claimedAt: Date | null = null;
+
+  @Column({ type: "text", nullable: true })
+  completedById: string | null = null;
+
+  @Column({ type: "datetime", nullable: true })
+  completedAt: Date | null = null;
+
+  @Column({ type: "json", nullable: true })
+  output: Record<string, unknown> | null = null;
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+}

package/core/workflow/tasks_module/services/IWorkflowTasks.service.ts

@@ -0,0 +1,52 @@
+import type { FormSpec } from "../../../../library/workflow";
+import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { TaskStatus } from "../model/WfTask.model";
+
+export interface TaskDetails {
+  readonly id: string;
+  readonly instanceId: string;
+  readonly tokenId: string;
+  readonly processKey: string;
+  readonly nodeId: string;
+  readonly partition: string | null;
+  readonly title: string;
+  readonly assignee: string;
+  readonly form: FormSpec | null;
+  readonly dueAt: Date | null;
+  readonly status: TaskStatus;
+  readonly claimedBy: string | null;
+  readonly claimedAt: Date | null;
+  readonly completedBy: string | null;
+  readonly completedAt: Date | null;
+  readonly output: Record<string, unknown> | null;
+  readonly createdAt: Date;
+}
+
+export interface TaskListQuery extends WorkflowPaging {
+  /** Tasks addressed to any of these (`role:support`, `user:42`), plus those the actor claimed. */
+  readonly assignees: readonly string[];
+  /** Whose claimed tasks count as theirs. */
+  readonly actor?: WorkflowActor;
+  /** `open` and `claimed` by default. */
+  readonly status?: readonly TaskStatus[];
+  readonly partition?: string;
+  readonly processKey?: string;
+}
+
+/**
+ * Tasks for people (WORKFLOW-001 §5): the inbox of `userTask` steps. A task
+ * appears when its step starts waiting and is cancelled when the step closes
+ * otherwise. Errors are {@link WorkflowError}: `not_found`, `conflict` (claimed
+ * by another person), `wrong_status`, `invalid_input` with the form issues.
+ */
+export abstract class IWorkflowTasks {
+  /** The tasks of these assignees, oldest first. */
+  abstract list(query: TaskListQuery): Promise<WorkflowPage<TaskDetails>>;
+  abstract get(taskId: string): Promise<TaskDetails>;
+  /** Takes an open task: nobody else can complete it until it is released. */
+  abstract claim(taskId: string, actor: WorkflowActor): Promise<TaskDetails>;
+  /** Gives a claimed task back. */
+  abstract release(taskId: string, actor: WorkflowActor): Promise<TaskDetails>;
+  /** Fills the form: the process moves on. */
+  abstract complete(taskId: string, output: unknown, actor: WorkflowActor): Promise<TaskDetails>;
+}

package/core/workflow/tasks_module/services/WorkflowTasks.service.ts

@@ -0,0 +1,167 @@
+import { UniqueViolationError } from "../../../orm";
+import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
+import { WorkflowError } from "../../contracts/WorkflowError";
+import type { WorkflowInstancesDeleted, WorkflowTaskRequested, WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
+import type { IWorkflowRuntime } from "../../runtime_module/services/IWorkflowRuntime.service";
+import type { TasksDbContext } from "../model/Tasks.dbContext";
+import { WfTask, type TaskStatus } from "../model/WfTask.model";
+import { IWorkflowTasks, type TaskDetails, type TaskListQuery } from "./IWorkflowTasks.service";
+
+const STATUSES = new Set<TaskStatus>(["open", "claimed", "completed", "cancelled"]);
+
+export class WorkflowTasks extends IWorkflowTasks {
+  constructor(
+    private readonly db: TasksDbContext,
+    private readonly runtime: IWorkflowRuntime,
+  ) {
+    super();
+  }
+
+  async list(query: TaskListQuery): Promise<WorkflowPage<TaskDetails>> {
+    const { limit, offset } = pagingOf(query);
+    const statuses = [...(query.status ?? ["open", "claimed"])];
+    if (statuses.length === 0 || statuses.some((status) => !STATUSES.has(status))) throw new WorkflowError("invalid_input", "status must be open, claimed, completed or cancelled");
+    const assignees = [...query.assignees];
+    const mine = query.actor?.id;
+    if (assignees.length === 0 && mine === undefined) return { items: [], total: 0 };
+    let source = this.db.tasks.asNoTracking().where((t) => t.status.in(statuses));
+    source = mine === undefined
+      ? source.where((t) => t.assignee.in(assignees))
+      : assignees.length === 0
+        ? source.where((t) => t.claimedById.eq(mine))
+        : source.where((t) => t.assignee.in(assignees).or(t.claimedById.eq(mine)));
+    if (query.partition !== undefined) source = source.where((t) => t.partition.eq(query.partition!));
+    if (query.processKey !== undefined) source = source.where((t) => t.processKey.eq(query.processKey!));
+    const total = await source.count();
+    const rows = await source.orderBy((t) => t.id).skip(offset).take(limit).toList();
+    return { items: rows.map(detailsOf), total };
+  }
+
+  async get(taskId: string): Promise<TaskDetails> {
+    return detailsOf(await this.task(taskId, false));
+  }
+
+  async claim(taskId: string, actor: WorkflowActor): Promise<TaskDetails> {
+    return await this.db.transactionScope(async () => {
+      const task = await this.locked(taskId);
+      if (task.status === "claimed" && task.claimedById === actor.id) return detailsOf(task);
+      if (task.status === "claimed") throw new WorkflowError("conflict", "The task is taken by someone else");
+      if (task.status !== "open") throw new WorkflowError("wrong_status", `The task is ${task.status}`);
+      task.status = "claimed";
+      task.claimedById = actor.id;
+      task.claimedAt = new Date();
+      await this.db.saveChanges();
+      return detailsOf(task);
+    });
+  }
+
+  async release(taskId: string, actor: WorkflowActor): Promise<TaskDetails> {
+    return await this.db.transactionScope(async () => {
+      const task = await this.locked(taskId);
+      if (task.status !== "claimed" || task.claimedById !== actor.id) throw new WorkflowError("wrong_status", "Only the person who took the task gives it back");
+      task.status = "open";
+      task.claimedById = null;
+      task.claimedAt = null;
+      await this.db.saveChanges();
+      return detailsOf(task);
+    });
+  }
+
+  async complete(taskId: string, output: unknown, actor: WorkflowActor): Promise<TaskDetails> {
+    const task = await this.task(taskId, false);
+    if (task.status === "claimed" && task.claimedById !== actor.id) throw new WorkflowError("conflict", "The task is taken by someone else");
+    if (task.status !== "open" && task.status !== "claimed") throw new WorkflowError("wrong_status", `The task is ${task.status}`);
+    let instance;
+    try {
+      // The form is checked and the process moves on first; the task follows.
+      instance = await this.runtime.completeToken(task.tokenId, output, actor);
+    } catch (error) {
+      if (error instanceof WorkflowError && error.code === "wrong_status") await this.close(task.tokenId, "cancelled");
+      throw error;
+    }
+    const saved = instance.nodes[task.nodeId];
+    await this.db.tasks.asNoTracking().where((t) => t.id.eq(task.id)).executeUpdate({
+      status: "completed",
+      completedById: actor.id,
+      completedAt: new Date(),
+      output: typeof saved === "object" && saved !== null && !Array.isArray(saved) ? saved as Record<string, unknown> : null,
+    });
+    return await this.get(task.id);
+  }
+
+  /** A step started waiting for a person: its task. Repeated events of one token make one task. */
+  async requested(event: WorkflowTaskRequested): Promise<void> {
+    const assignee = "role" in event.assignee ? `role:${event.assignee.role}` : `user:${event.assignee.user}`;
+    this.db.tasks.add(Object.assign(new WfTask(), {
+      tokenId: event.tokenId,
+      instanceId: event.instanceId,
+      processKey: event.processKey,
+      nodeId: event.nodeId,
+      partition: event.partition,
+      title: event.title,
+      assignee,
+      form: event.form,
+      dueAt: event.dueAt,
+    }));
+    try {
+      await this.db.saveChanges();
+    } catch (error) {
+      if (!(error instanceof UniqueViolationError)) throw error;
+    }
+  }
+
+  /** The step closed otherwise than by its task: the task is cancelled. */
+  async closed(event: WorkflowTokenClosed): Promise<void> {
+    await this.close(event.tokenId, "cancelled");
+  }
+
+  /** Retention deleted the instances: their tasks go too. */
+  async deleted(event: WorkflowInstancesDeleted): Promise<void> {
+    if (event.instanceIds.length > 0) await this.db.tasks.asNoTracking().where((t) => t.instanceId.in([...event.instanceIds])).executeDelete();
+  }
+
+  private async close(tokenId: string, status: "cancelled"): Promise<void> {
+    await this.db.tasks.asNoTracking().where((t) => t.tokenId.eq(tokenId).and(t.status.in(["open", "claimed"]))).executeUpdate({ status });
+  }
+
+  private async task(taskId: string, tracked: boolean): Promise<WfTask> {
+    if (!isUuid(taskId)) throw notFound(taskId);
+    const source = tracked ? this.db.tasks : this.db.tasks.asNoTracking();
+    const task = await source.firstOrDefault((t) => t.id.eq(taskId));
+    if (!task) throw notFound(taskId);
+    return task;
+  }
+
+  private async locked(taskId: string): Promise<WfTask> {
+    if (!isUuid(taskId)) throw notFound(taskId);
+    const task = await this.db.tasks.where((t) => t.id.eq(taskId)).forUpdate().firstOrDefault();
+    if (!task) throw notFound(taskId);
+    return task;
+  }
+}
+
+function notFound(taskId: string): WorkflowError {
+  return new WorkflowError("not_found", `Task ${taskId} does not exist`);
+}
+
+function detailsOf(row: WfTask): TaskDetails {
+  return {
+    id: row.id,
+    instanceId: row.instanceId,
+    tokenId: row.tokenId,
+    processKey: row.processKey,
+    nodeId: row.nodeId,
+    partition: row.partition,
+    title: row.title,
+    assignee: row.assignee,
+    form: row.form,
+    dueAt: row.dueAt,
+    status: row.status,
+    claimedBy: row.claimedById,
+    claimedAt: row.claimedAt,
+    completedBy: row.completedById,
+    completedAt: row.completedAt,
+    output: row.output,
+    createdAt: row.createdAt,
+  };
+}

package/library/workflow/cron.ts

@@ -0,0 +1,89 @@
+/** A parsed five-field cron expression, evaluated in UTC. */
+export interface CronSchedule {
+  /** Whether the expression fires at this minute. */
+  matches(date: Date): boolean;
+  /** The first minute after `after` when it fires; `undefined` if none within five years. */
+  next(after: Date): Date | undefined;
+}
+
+const FIELDS = [
+  { min: 0, max: 59 },
+  { min: 0, max: 23 },
+  { min: 1, max: 31 },
+  { min: 1, max: 12 },
+  { min: 0, max: 7 },
+] as const;
+
+const MINUTE = 60_000;
+
+/**
+ * Parses `minute hour day-of-month month day-of-week` with `*`, numbers,
+ * ranges `a-b`, steps `/n` and lists `a,b`. Day of week 0 and 7 are Sunday.
+ * When both day fields are restricted, either one matching is enough, as in
+ * classic cron. Returns `undefined` for an invalid expression.
+ */
+export function parseCron(expression: string): CronSchedule | undefined {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) return undefined;
+  const sets: Set<number>[] = [];
+  for (const [index, part] of parts.entries()) {
+    const set = field(part, FIELDS[index]!.min, FIELDS[index]!.max);
+    if (set === undefined) return undefined;
+    sets.push(set);
+  }
+  const [minutes, hours, days, months, weekdays] = sets as [Set<number>, Set<number>, Set<number>, Set<number>, Set<number>];
+  if (weekdays.has(7)) weekdays.add(0);
+  const daysRestricted = parts[2] !== "*";
+  const weekdaysRestricted = parts[4] !== "*";
+
+  const dayMatches = (date: Date): boolean => {
+    const day = days.has(date.getUTCDate());
+    const weekday = weekdays.has(date.getUTCDay());
+    return daysRestricted && weekdaysRestricted ? day || weekday : day && weekday;
+  };
+
+  const matches = (date: Date): boolean =>
+    minutes.has(date.getUTCMinutes()) && hours.has(date.getUTCHours()) && months.has(date.getUTCMonth() + 1) && dayMatches(date);
+
+  return {
+    matches,
+    next(after: Date): Date | undefined {
+      const limit = after.getTime() + 5 * 366 * 24 * 60 * MINUTE;
+      const date = new Date(Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE);
+      while (date.getTime() <= limit) {
+        if (!months.has(date.getUTCMonth() + 1)) {
+          date.setUTCMonth(date.getUTCMonth() + 1, 1);
+          date.setUTCHours(0, 0, 0, 0);
+        } else if (!dayMatches(date)) {
+          date.setUTCDate(date.getUTCDate() + 1);
+          date.setUTCHours(0, 0, 0, 0);
+        } else if (!hours.has(date.getUTCHours())) {
+          date.setUTCHours(date.getUTCHours() + 1, 0, 0, 0);
+        } else if (!minutes.has(date.getUTCMinutes())) {
+          date.setTime(date.getTime() + MINUTE);
+        } else {
+          return date;
+        }
+      }
+      return undefined;
+    },
+  };
+}
+
+function field(text: string, min: number, max: number): Set<number> | undefined {
+  const out = new Set<number>();
+  for (const item of text.split(",")) {
+    const match = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(item);
+    if (!match) return undefined;
+    const step = match[2] === undefined ? 1 : Number(match[2]);
+    let from = min, to = max;
+    if (match[1] !== "*") {
+      const [a, b] = match[1]!.split("-").map(Number) as [number, number | undefined];
+      from = a;
+      to = b ?? (match[2] === undefined ? a : max);
+    }
+    if (step < 1 || from < min || to > max || from > to) return undefined;
+    for (let value = from; value <= to; value += step) out.add(value);
+  }
+  return out;
+}

package/library/workflow/index.ts

@@ -21,4 +21,5 @@ export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type Pro
 export { DATA_PATH, isPath, readPath, resolveInput, type InstanceData } from "./paths";
 export { evaluateCondition } from "./conditions";
 export { durationMs } from "./duration";
+export { parseCron, type CronSchedule } from "./cron";
 export { checkFormSpec, formFieldCodes, validateForm, type FormField, type FormFieldType, type FormIssue, type FormSpec } from "./formFields";

package/library/workflow/nodeKinds.ts

@@ -1,3 +1,4 @@
+import { parseCron } from "./cron";
 import { checkFormSpec } from "./formFields";
 import { DATA_PATH } from "./paths";
 import type { NodeKind } from "./ProcessDocument";
@@ -42,8 +43,7 @@ function first(...checks: (string | null)[]): string | null {
 function cron(config: Record<string, unknown>): string | null {
   const value = config.cron;
   if (typeof value !== "string") return "config.cron is required";
-  const parts = value.trim().split(/\s+/);
-  return parts.length === 5 && parts.every((part) => /^[\d*/,\-]+$/.test(part)) ? null : "config.cron must have five fields";
+  return parseCron(value) === undefined ? "config.cron must be five valid fields: minute hour day month weekday (UTC)" : null;
 }
 
 /** A timer: either `duration` (ISO 8601) or `at`, a path to a date in instance data. */
@@ -99,7 +99,7 @@ export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
   { kind: "parallelGateway", role: "gateway", check: none },
   { kind: "boundaryError", role: "boundary", check: (c) => string(c, "errorCode", /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, false) },
   { kind: "boundaryTimer", role: "boundary", check: (c) => first(timer(c), boolean(c, "interrupting")) },
-  { kind: "boundaryEvent", role: "boundary", check: (c) => first(string(c, "event", DOTTED_KEY), boolean(c, "interrupting")) },
+  { kind: "boundaryEvent", role: "boundary", check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), boolean(c, "interrupting")) },
   { kind: "end", role: "end", check: none },
 ] satisfies NodeKindDefinition[]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.125.0",
+  "version": "0.127.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",