bazis 0.125.0 → 0.126.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.126.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/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/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/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/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/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.126.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",