bazis 0.124.1 → 0.126.0

package/core/agent/AgentToolExecutor.ts

@@ -2146,7 +2146,7 @@ export class AgentToolExecutor {
     details?: JsonObject,
   ): AgentToolResult {
     if (error instanceof ToolError) {
-      return this.errorResult(call, code, error.message, metadata, startedAt, details);
+      return this.errorResult(call, code, error.message, metadata, startedAt, error.reason === undefined ? details : { ...details, reason: error.reason });
     }
     this.logger?.error("Agent tool failed", { agent: agentName ?? null, tool: call.name, callId: call.id, code, error: redactSensitive(error) });
     return this.errorResult(call, code, fallback, metadata, startedAt, details);

package/core/agent/errors.ts

@@ -29,9 +29,20 @@ export class AgentToolExecutionError extends Error {
  * goes to the application log with its stack.
  */
 export class ToolError extends Error {
-  constructor(message: string) {
+  /**
+   * A business reason the caller can act on, such as `card_declined`: it comes
+   * back as `error.details.reason`. A process routes it to an error boundary
+   * and does not retry it (WORKFLOW-001).
+   */
+  readonly reason?: string;
+
+  constructor(message: string, options: { readonly reason?: string } = {}) {
     super(message);
     this.name = "ToolError";
+    if (options.reason !== undefined) {
+      if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(options.reason)) throw new TypeError("ToolError reason must match ^[A-Za-z][A-Za-z0-9_.-]{0,63}$");
+      this.reason = options.reason;
+    }
   }
 }
 
@@ -41,8 +52,8 @@ export class ToolError extends Error {
  * for an idempotency-gated retry. Its message reaches the model like a ToolError.
  */
 export class AgentToolPreCommitError extends ToolError {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options: { readonly reason?: string } = {}) {
+    super(message, options);
     this.name = "AgentToolPreCommitError";
   }
 }

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.124.1" }, 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,11 @@ 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";
 import { RUNTIME_ENTITIES, RuntimeDbContext, runtimeStore } from "./model/Runtime.dbContext";
@@ -35,6 +38,8 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
       resolver.tryResolve(LOGGER),
     ))),
     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),
@@ -43,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,12 +2,19 @@ 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";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
 
 /** How long a claimed job belongs to this worker; if it dies, another one takes the job after that. */
 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;
 
 
 /**
@@ -28,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);
@@ -48,9 +60,44 @@ export class WorkflowWorker extends BackgroundService {
   private async run(job: WfJob, signal: AbortSignal): Promise<void> {
     const scope = this.services.createScope();
     try {
-      await scope.resolve(ToolStep).run(job, signal);
+      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 });
+      await this.giveUpOrDelay(job, error).catch((failure: unknown) => this.reportFailure("job failure handling failed", failure, { job: job.id }));
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  private async reconcile(): Promise<void> {
+    const scope = this.services.createScope();
+    try {
+      await scope.resolve(Schedules).reconcile();
     } catch (error) {
-      this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId });
+      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);
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      if (job.attempts < MAX_JOB_ATTEMPTS || job.instanceId === null || job.tokenId === null) {
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: new Date(Date.now() + job.attempts * 60_000), lockedUntil: null, lastError: message.slice(0, 1000) });
+        return;
+      }
+      const engine = scope.resolve(WorkflowEngine);
+      await engine.inStep(job.instanceId, async (step) => {
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+        const token = step.tokens.find((t) => t.id === job.tokenId);
+        if (token && token.status === "waiting" && step.instance.status === "running") engine.fail(step, token, "job_failed", message.slice(0, 1000));
+      });
     } finally {
       await scope.dispose();
     }
@@ -63,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.eq("tool").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

@@ -20,7 +20,8 @@ export interface WorkflowTaskRequested {
 export interface WorkflowTokenClosed {
   readonly instanceId: string;
   readonly tokenId: string;
-  readonly reason: "cancelled";
+  /** `cancelled` — the instance was cancelled; `interrupted` — a boundary timer took over the step. */
+  readonly reason: "cancelled" | "interrupted";
 }
 
 /** An instance finished: completed or cancelled. */

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

@@ -1,4 +1,4 @@
-import type { ProcessDocument, ProcessFlow } from "../../../../library/workflow";
+import type { ProcessDocument, ProcessFlow, ProcessNode } from "../../../../library/workflow";
 
 /** A version's graph with flows indexed by node. Built once per version. */
 export interface ProcessGraph {
@@ -8,6 +8,8 @@ export interface ProcessGraph {
   readonly document: ProcessDocument;
   readonly outgoing: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
   readonly incoming: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
+  /** Boundary nodes by the step they are attached to. */
+  readonly boundaries: ReadonlyMap<string, readonly (readonly [string, ProcessNode])[]>;
 }
 
 export function buildGraph(versionId: string, processKey: string, version: number, document: ProcessDocument): ProcessGraph {
@@ -17,7 +19,11 @@ export function buildGraph(versionId: string, processKey: string, version: numbe
     outgoing.set(flow.source, [...outgoing.get(flow.source) ?? [], [id, flow]]);
     incoming.set(flow.target, [...incoming.get(flow.target) ?? [], [id, flow]]);
   }
-  return { versionId, processKey, version, document, outgoing, incoming };
+  const boundaries = new Map<string, (readonly [string, ProcessNode])[]>();
+  for (const [id, node] of Object.entries(document.nodes)) {
+    if (node.attachedTo !== undefined) boundaries.set(node.attachedTo, [...boundaries.get(node.attachedTo) ?? [], [id, node]]);
+  }
+  return { versionId, processKey, version, document, outgoing, incoming, boundaries };
 }
 
 /** Graphs of versions in memory. Versions are immutable, so entries never go stale; the oldest go first past the limit. */

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

@@ -0,0 +1,21 @@
+import type { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfJob } from "../model/WfJob.model";
+import type { WorkflowEngine } from "./WorkflowEngine";
+
+/** One `timer` job: a `timerCatch` step or a boundary timer is due. A closed token drops it. */
+export class TimerStep {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+  ) {}
+
+  async run(job: WfJob): Promise<void> {
+    const fired = job.instanceId === null || job.tokenId === null
+      ? null
+      : await this.engine.inStep(job.instanceId, async (step) => {
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+        return await this.engine.timerFired(step, job.tokenId!);
+      });
+    if (fired === null) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+  }
+}

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

@@ -1,5 +1,5 @@
 import type { AgentToolResult } from "../../../agent";
-import { resolveInput } from "../../../../library/workflow";
+import { durationMs, resolveInput } from "../../../../library/workflow";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
@@ -40,21 +40,57 @@ export class ToolStep {
         signal,
       });
 
+    const reason = reasonOf(result);
     await this.engine.inStep(instance.id, async (step) => {
-      await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       const current = step.tokens.find((t) => t.id === token.id);
+      const retryAt = current?.status === "waiting" && step.instance.status === "running" && result.status === "error" && reason === undefined
+        ? nextAttempt(node?.config?.retry, job.attempts)
+        : undefined;
+      if (retryAt !== undefined) {
+        // The same job runs again later: its attempts keep counting.
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: retryAt, lockedUntil: null, lastError: result.error?.message ?? null });
+      } else {
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+      }
       if (!current || current.status !== "waiting" || step.instance.status !== "running") return;
       this.engine.history(step, current, current.nodeId, "tool", {
         tool: name,
         status: result.status,
+        attempt: job.attempts,
         durationMs: result.durationMs ?? null,
-        ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message } } : {}),
+        ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message, ...(reason === undefined ? {} : { reason }) } } : {}),
+        ...(retryAt === undefined ? {} : { retryAt: retryAt.toISOString() }),
       });
+      if (retryAt !== undefined) return;
       if (result.status === "success") {
         await this.engine.complete(step, current.id, result.output ?? null);
       } else {
-        this.engine.fail(step, current, result.error?.code ?? "TOOL_FAILED", result.error?.message ?? `Tool ${name} failed`);
+        await this.engine.failStep(step, current, {
+          code: result.error?.code ?? "TOOL_FAILED",
+          message: result.error?.message ?? `Tool ${name} failed`,
+          ...(reason === undefined ? {} : { reason }),
+        });
       }
     });
   }
 }
+
+/** The business reason of a `ToolError`, if the Tool gave one. */
+function reasonOf(result: AgentToolResult): string | undefined {
+  const details = result.error?.details;
+  const reason = typeof details === "object" && details !== null && !Array.isArray(details) ? (details as Record<string, unknown>).reason : undefined;
+  return typeof reason === "string" ? reason : undefined;
+}
+
+/**
+ * When to try a failed call again under the node's `retry` policy, or
+ * `undefined` when the attempts are used up. The pause doubles from `backoff`
+ * (10 seconds by default) and stops growing at a day.
+ */
+export function nextAttempt(policy: unknown, attempts: number): Date | undefined {
+  if (typeof policy !== "object" || policy === null) return undefined;
+  const { maxAttempts, backoff } = policy as { maxAttempts?: unknown; backoff?: unknown };
+  if (typeof maxAttempts !== "number" || attempts >= maxAttempts) return undefined;
+  const base = typeof backoff === "string" ? durationMs(backoff) ?? 10_000 : 10_000;
+  return new Date(Date.now() + Math.min(base * 2 ** Math.max(attempts - 1, 0), 86_400_000));
+}

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

@@ -1,6 +1,6 @@
 import type { ServiceResolver } from "../../../di";
 import { EventBus, type EventToken, type Logger } from "../../../kernel";
-import { durationMs, evaluateCondition, nodeKindOf, type FormSpec, type InstanceData, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
+import { durationMs, evaluateCondition, nodeKindOf, readPath, type FormSpec, type InstanceData, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
 import type { WorkflowActor } from "../../contracts/types";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import { WORKFLOW_INSTANCE_FINISHED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED } from "../events/Runtime.events";
@@ -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(["timerCatch", "eventWait"]);
 const LIVE = new Set(["active", "waiting", "failed"]);
 
 /**
@@ -132,12 +131,91 @@ export class WorkflowEngine {
     const saveTo = node.config?.saveTo;
     if (typeof saveTo === "string") step.instance.vars = { ...step.instance.vars, [saveTo]: output ?? null };
     if (actor !== undefined) this.history(step, token, token.nodeId, "completed", null, actor);
+    this.disarm(step, token.nodeId);
+    await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
+    return true;
+  }
+
+  /**
+   * A step's Tool failed for good. An error boundary attached to the step takes
+   * the token (first one whose `errorCode` equals the Tool's `reason` or error
+   * code, else one without `errorCode`); otherwise the instance fails.
+   */
+  async failStep(step: Step, token: WfToken, error: { readonly code: string; readonly message: string; readonly reason?: string }): Promise<void> {
+    const boundaries = (step.graph.boundaries.get(token.nodeId) ?? []).filter(([, node]) => node.kind === "boundaryError");
+    const matching = boundaries.find(([, node]) => node.config?.errorCode !== undefined && (node.config.errorCode === error.reason || node.config.errorCode === error.code))
+      ?? boundaries.find(([, node]) => node.config?.errorCode === undefined);
+    if (!matching) {
+      this.fail(step, token, error.code, error.message);
+      return;
+    }
+    const [boundaryId] = matching;
+    const caught = { code: error.code, message: error.message, ...(error.reason === undefined ? {} : { reason: error.reason }) };
+    token.output = { error: caught };
+    this.close(token, "done");
+    this.disarm(step, token.nodeId);
+    this.history(step, token, token.nodeId, "error", { ...caught, boundary: boundaryId });
+    step.instance.nodes = { ...step.instance.nodes, [boundaryId]: caught };
+    await this.advance(step, [this.spawn(step, boundaryId, null)]);
+  }
+
+  /**
+   * A timer job is due. A `timerCatch` step moves on. A `boundaryTimer` takes
+   * its own flow; an interrupting one (the default) first closes the step it
+   * watches. `false` when the token no longer waits.
+   */
+  async timerFired(step: Step, tokenId: string): 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];
+    const firedAt = new Date().toISOString();
+    if (node?.kind === "timerCatch") {
+      this.history(step, token, token.nodeId, "timer", { firedAt });
+      return await this.complete(step, tokenId, { firedAt });
+    }
+    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, 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");
+        if (step.graph.document.nodes[host.nodeId]?.kind === "userTask") {
+          step.events.push({ event: WORKFLOW_TOKEN_CLOSED as EventToken<unknown>, payload: { instanceId: step.instance.id, tokenId: host.id, reason: "interrupted" } });
+        }
+      }
+      this.disarm(step, node.attachedTo, token.id);
+    }
+    step.instance.nodes = { ...step.instance.nodes, [token.nodeId]: output };
     await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
     return true;
   }
 
   /** A step failed: the token waits for a retry, the instance is `failed` with the reason. */
   fail(step: Step, token: WfToken, code: string, message: string): void {
+    this.disarm(step, token.nodeId);
     token.status = "failed";
     step.instance.status = "failed";
     step.instance.error = { node: token.nodeId, code, message };
@@ -219,15 +297,17 @@ export class WorkflowEngine {
       this.close(token, "done");
       return [];
     }
-    if (NOT_YET.has(node.kind)) {
-      this.fail(step, token, "not_supported", `${node.kind} steps are not supported yet`);
-      return [];
-    }
+    // 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));
     switch (node.kind) {
       case "serviceTask":
-        return this.waitForTool(step, token);
+        return this.arm(step, token, this.waitForTool(step, token));
       case "userTask":
-        return this.waitForTask(step, token, node);
+        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":
@@ -238,6 +318,79 @@ export class WorkflowEngine {
     }
   }
 
+  private waitForTimer(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
+    const dueAt = timerDue(node.config ?? {}, dataOf(step.instance));
+    if (dueAt === undefined) {
+      this.fail(step, token, "bad_timer", `the timer of ${token.nodeId} has no valid date`);
+      return [];
+    }
+    token.status = "waiting";
+    this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "timer" as const, instanceId: step.instance.id, tokenId: token.id, dueAt }));
+    return [];
+  }
+
+  /**
+   * A step started waiting: its boundary timers start too, each as a waiting
+   * token on the boundary node with a timer job.
+   */
+  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) {
+        this.fail(step, host, "bad_timer", `the timer of ${id} has no valid date`);
+        return [];
+      }
+      const watcher = this.spawn(step, id, null);
+      watcher.status = "waiting";
+      this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "timer" as const, instanceId: step.instance.id, tokenId: watcher.id, dueAt }));
+    }
+    return next;
+  }
+
+  /** The step left or failed: its boundary tokens close; their jobs find the tokens closed and drop. */
+  private disarm(step: Step, hostNodeId: string, except?: string): void {
+    const boundaries = new Set((step.graph.boundaries.get(hostNodeId) ?? []).map(([id]) => id));
+    if (boundaries.size === 0) return;
+    for (const token of step.tokens) {
+      if (token.id !== except && boundaries.has(token.nodeId) && LIVE.has(token.status)) this.close(token, "cancelled");
+    }
+  }
+
+  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() }));
@@ -351,6 +504,31 @@ export class WorkflowEngine {
   }
 }
 
+/** When a timer fires: `duration` from now, or the date at the `at` path; `undefined` if neither is valid. */
+export function timerDue(config: Readonly<Record<string, unknown>>, data: InstanceData): Date | undefined {
+  if (typeof config.duration === "string") {
+    const ms = durationMs(config.duration);
+    return ms === undefined ? undefined : new Date(Date.now() + ms);
+  }
+  if (typeof config.at === "string") {
+    const value = readPath(data, config.at);
+    const date = value instanceof Date ? value : typeof value === "string" || typeof value === "number" ? new Date(value) : undefined;
+    return date === undefined || Number.isNaN(date.getTime()) ? undefined : date;
+  }
+  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.124.1",
+  "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",