bazis 0.133.0 → 0.135.0

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

@@ -1,16 +1,18 @@
 import { grantsToWhere } from "../../../access";
-import { paginate } from "../../../orm";
-import { inputSpecOf, type FormIssue, type FormSpec } from "../../../../library/workflow";
+import { paginate, type OrmTransaction } from "../../../orm";
+import { inputSpecOf, type FormSpec } from "../../../../library/workflow";
 import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import type { ServiceProvider } from "../../../di";
 import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
 import type { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { EventDelivery, EventMessage } from "../internal/EventDelivery";
 import type { WorkflowEngine } from "../internal/WorkflowEngine";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfHistory } from "../model/WfHistory.model";
 import type { WfInstance } from "../model/WfInstance.model";
+import { WfJob } from "../model/WfJob.model";
 import type { WfToken } from "../model/WfToken.model";
 import {
   IWorkflowRuntime,
@@ -35,6 +37,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
   constructor(
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
+    private readonly delivery: EventDelivery,
     private readonly definitions: IWorkflowDefinitions,
     /** The scope: the input validator is asked here, so that the application's own registration replaces the default. */
     private readonly services: ServiceProvider,
@@ -52,7 +55,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
     const { value, issues } = await this.validator().validate(inputSpecOf(version.document), options.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
     if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
-    const { id, skipped } = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
+    const { id, skipped } = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null, ...(options.test === true ? { test: true } : {}) });
     if (skipped) throw new WorkflowError("conflict", `Instance ${id} with this businessKey is not finished`);
     return await this.instance(id);
   }
@@ -135,45 +138,14 @@ export class WorkflowRuntime extends IWorkflowRuntime {
   }
 
   async emit(eventKey: string, payload: unknown = {}, options: EmitOptions = {}): Promise<EmitResult> {
-    if (typeof eventKey !== "string" || !EVENT_KEY.test(eventKey)) throw new WorkflowError("invalid_input", "eventKey must look like payments.received");
-    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new WorkflowError("invalid_input", "payload must be a JSON object");
-    const data = payload as Record<string, unknown>;
-    const correlation = optionalText(options.correlation, "correlation");
-    const partition = optionalText(options.partition, "partition");
-    const actor = options.actor ?? { kind: "system" as const, id: `event:${eventKey}` };
-    actorOf(actor);
-
-    let waits = this.db.subscriptions.asNoTracking().where((s) => s.eventKey.eq(eventKey));
-    waits = correlation === null ? waits.where((s) => s.correlation.isNull()) : waits.where((s) => s.correlation.isNull().or(s.correlation.eq(correlation)));
-    if (partition !== null) waits = waits.where((s) => s.partition.eq(partition));
-    const continued = new Set<string>();
-    for (const wait of await waits.orderBy((s) => s.id).toList()) {
-      const moved = await this.engine.inStep(wait.instanceId, async (step) => {
-        await this.db.subscriptions.asNoTracking().where((s) => s.id.eq(wait.id)).executeDelete();
-        return await this.engine.eventReceived(step, wait.tokenId, eventKey, data);
-      });
-      if (moved === true) continued.add(wait.instanceId);
-    }
+    return await this.delivery.emit(messageOf(eventKey, payload, options));
+  }
 
-    const started: string[] = [];
-    const skipped: { processKey: string; instanceId: string }[] = [];
-    const rejected: { processKey: string; issues: readonly FormIssue[] }[] = [];
-    for (const version of await this.definitions.published()) {
-      for (const [nodeId, node] of Object.entries(version.document.nodes)) {
-        if (node.kind !== "eventStart" || node.config?.event !== eventKey) continue;
-        // An event carries more than a process needs: fields the input does not declare are dropped, not refused.
-        const { value, issues: all } = await this.validator().validate(inputSpecOf(version.document), data, { purpose: "input", processKey: version.key, partition, language: this.languages.default, actor });
-        const issues = all.filter((issue) => issue.code !== "unknown");
-        if (issues.length > 0) {
-          rejected.push({ processKey: version.key, issues });
-          continue;
-        }
-        const begun = await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null, event: { key: eventKey, payload: data } });
-        if (begun.skipped) skipped.push({ processKey: version.key, instanceId: begun.id });
-        else started.push(begun.id);
-      }
-    }
-    return { started, skipped, continued: [...continued], rejected };
+  async emitLater(tx: OrmTransaction, eventKey: string, payload: unknown = {}, options: EmitOptions = {}): Promise<void> {
+    const message = messageOf(eventKey, payload, options);
+    const now = this.engine.now();
+    const job = Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "event" as const, partition: message.partition, dueAt: now, payload: message, createdAt: now });
+    await tx.use(this.db, (db) => db.jobs.insertIfAbsent(job, { conflictBy: (j) => [j.id] }));
   }
 
   async instances(query: InstanceListQuery = {}): Promise<WorkflowPage<InstanceSummary>> {
@@ -188,6 +160,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (query.businessKey !== undefined) source = source.where((i) => i.businessKey.eq(query.businessKey!));
     if (query.startedById !== undefined) source = source.where((i) => i.startedById.eq(query.startedById!));
     if (query.parentInstanceId !== undefined) source = source.where((i) => i.parentInstanceId.eq(query.parentInstanceId!));
+    if (query.test !== undefined || query.parentInstanceId === undefined) source = source.where((i) => i.test.eq(query.test === true));
     const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "desc" }));
     return { items: items.map(summaryOf), total };
   }
@@ -214,6 +187,23 @@ export class WorkflowRuntime extends IWorkflowRuntime {
   }
 }
 
+/** An event as the delivery takes it; what cannot be delivered is refused here. */
+function messageOf(eventKey: string, payload: unknown, options: EmitOptions): EventMessage {
+  if (typeof eventKey !== "string" || !EVENT_KEY.test(eventKey)) throw new WorkflowError("invalid_input", "eventKey must look like payments.received");
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw new WorkflowError("invalid_input", "payload must be a JSON object");
+  const actor = options.actor ?? { kind: "system" as const, id: `event:${eventKey}` };
+  actorOf(actor);
+  return {
+    eventKey,
+    payload: payload as Record<string, unknown>,
+    correlation: optionalText(options.correlation, "correlation"),
+    partition: optionalText(options.partition, "partition"),
+    actor,
+    request: options.request ?? null,
+    cause: options.cause ?? null,
+  };
+}
+
 function notFound(instanceId: string): WorkflowError {
   return new WorkflowError("not_found", `Instance ${instanceId} does not exist`);
 }
@@ -242,11 +232,20 @@ function summaryOf(row: WfInstance): InstanceSummary {
     startedBy: { kind: row.startedByKind, id: row.startedById },
     parentInstanceId: row.parentInstanceId,
     error: row.error,
+    failedNode: row.error === null || row.error.node === "" ? null : row.error.node,
+    test: row.test,
     createdAt: row.createdAt,
     endedAt: row.endedAt,
+    durationMs: durationOf(row),
   };
 }
 
+/** From the start by the engine's clock: `createdAt` is the clock of the database. */
+function durationOf(row: WfInstance): number | null {
+  const startedAt = typeof row.trigger?.at === "string" ? Date.parse(row.trigger.at) : Number.NaN;
+  return row.endedAt === null || Number.isNaN(startedAt) ? null : row.endedAt.getTime() - startedAt;
+}
+
 function tokenOf(row: WfToken) {
   return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, parentTokenId: row.parentTokenId, iteration: row.iteration, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
 }

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

@@ -1,5 +1,5 @@
 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 { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, WORKFLOW_TRIAL_TASK_REQUESTED, WORKFLOW_TRIAL_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
 import type { TasksDbContext } from "../model/Tasks.dbContext";
 import { WfTask } from "../model/WfTask.model";
 
@@ -10,6 +10,16 @@ export class TaskEvents {
   /** A step started waiting for a person: its task. Repeated events of one token make one task. */
   @OnEvent(WORKFLOW_TASK_REQUESTED)
   async requested(event: WorkflowTaskRequested): Promise<void> {
+    await this.add(event, false);
+  }
+
+  /** The task of a trial run: it goes to who started it, and is marked. */
+  @OnEvent(WORKFLOW_TRIAL_TASK_REQUESTED)
+  async trialRequested(event: WorkflowTaskRequested): Promise<void> {
+    await this.add(event, true);
+  }
+
+  private async add(event: WorkflowTaskRequested, test: boolean): Promise<void> {
     const assignee = "role" in event.assignee ? `role:${event.assignee.role}` : `user:${event.assignee.user}`;
     // Past the change tracker: the scope may go on to update tasks directly, which a context holding one would refuse.
     await this.db.tasks.insertIfAbsent(Object.assign(new WfTask(), {
@@ -18,6 +28,7 @@ export class TaskEvents {
       processKey: event.processKey,
       nodeId: event.nodeId,
       partition: event.partition,
+      test,
       title: event.title,
       assignee,
       form: event.form,
@@ -32,6 +43,11 @@ export class TaskEvents {
     await this.db.tasks.asNoTracking().where((t) => t.tokenId.eq(event.tokenId).and(t.status.in(["open", "claimed"]))).executeUpdate({ status: "cancelled" });
   }
 
+  @OnEvent(WORKFLOW_TRIAL_TOKEN_CLOSED)
+  async trialClosed(event: WorkflowTokenClosed): Promise<void> {
+    await this.closed(event);
+  }
+
   /** Retention deleted the instances: their tasks go too. */
   @OnEvent(WORKFLOW_INSTANCES_DELETED)
   async deleted(event: WorkflowInstancesDeleted): Promise<void> {

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

@@ -11,6 +11,8 @@ export interface TaskDetails {
   readonly nodeId: string;
   readonly partition: string | null;
   readonly title: LocalizedText;
+  /** A task of a trial run. */
+  readonly test: boolean;
   readonly assignee: string;
   readonly form: FormSpec | null;
   readonly dueAt: Date | null;

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

@@ -100,7 +100,7 @@ export class WorkflowTasks extends IWorkflowTasks {
       completedAt: this.clock.now(),
       output: typeof saved === "object" && saved !== null && !Array.isArray(saved) ? saved as Record<string, unknown> : null,
     });
-    await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
+    if (!task.test) await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
     return await this.get(task.id);
   }
 
@@ -157,6 +157,7 @@ function detailsOf(row: WfTask): TaskDetails {
     nodeId: row.nodeId,
     partition: row.partition,
     title: row.title,
+    test: row.test,
     assignee: row.assignee,
     form: row.form,
     dueAt: row.dueAt,

package/library/workflow/cron.ts

@@ -1,4 +1,4 @@
-/** A parsed five-field cron expression, evaluated in UTC. */
+/** A parsed five-field cron expression, evaluated in UTC or in a time zone. */
 export interface CronSchedule {
   /** Whether the expression fires at this minute. */
   matches(date: Date): boolean;
@@ -15,14 +15,53 @@ const FIELDS = [
 ] as const;
 
 const MINUTE = 60_000;
+const DAY_MINUTES = 24 * 60;
+/** Clock changes are never longer than this: a day is skipped up to here, the rest hour by hour. */
+const CLOCK_CHANGE_MINUTES = 3 * 60;
+
+const formats = new Map<string, Intl.DateTimeFormat>();
+
+function formatOf(timezone: string): Intl.DateTimeFormat {
+  let format = formats.get(timezone);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat("en-US", { timeZone: timezone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+    formats.set(timezone, format);
+  }
+  return format;
+}
+
+/** Whether this is an IANA time zone: `Europe/Moscow`, `UTC`. */
+export function isTimeZone(value: unknown): value is string {
+  if (typeof value !== "string" || value === "") return false;
+  try {
+    formatOf(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** How far the clocks of the zone are ahead of UTC at this moment, in milliseconds. */
+function offsetOf(timezone: string | undefined, time: number): number {
+  if (timezone === undefined) return 0;
+  const parts: Record<string, number> = {};
+  for (const { type, value } of formatOf(timezone).formatToParts(time)) parts[type] = Number(value);
+  return Date.UTC(parts.year!, parts.month! - 1, parts.day!, parts.hour!, parts.minute!, parts.second!) - Math.floor(time / 1000) * 1000;
+}
 
 /**
  * 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.
+ * classic cron. Returns `undefined` for an invalid expression or time zone.
+ *
+ * With a `timezone` the fields are read on its clocks. A schedule with a set
+ * hour fires once a day whatever the clocks do: a time skipped when they go
+ * forward fires right after the change, a time repeated when they go back fires
+ * the first time only. A schedule with `*` in the hour simply follows the clocks.
  */
-export function parseCron(expression: string): CronSchedule | undefined {
+export function parseCron(expression: string, timezone?: string): CronSchedule | undefined {
+  if (timezone !== undefined && !isTimeZone(timezone)) return undefined;
   const parts = expression.trim().split(/\s+/);
   if (parts.length !== 5) return undefined;
   const sets: Set<number>[] = [];
@@ -35,34 +74,74 @@ export function parseCron(expression: string): CronSchedule | undefined {
   if (weekdays.has(7)) weekdays.add(0);
   const daysRestricted = parts[2] !== "*";
   const weekdaysRestricted = parts[4] !== "*";
+  const hourSet = parts[1] !== "*";
 
-  const dayMatches = (date: Date): boolean => {
-    const day = days.has(date.getUTCDate());
-    const weekday = weekdays.has(date.getUTCDay());
-    return daysRestricted && weekdaysRestricted ? day || weekday : day && weekday;
+  /** The date part of a time on the clocks of the zone, kept in the UTC fields of a `Date`. */
+  const dayMatches = (clock: Date): boolean => {
+    const day = days.has(clock.getUTCDate());
+    const weekday = weekdays.has(clock.getUTCDay());
+    return months.has(clock.getUTCMonth() + 1) && (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);
+  const clockMatches = (clock: Date): boolean => minutes.has(clock.getUTCMinutes()) && hours.has(clock.getUTCHours()) && dayMatches(clock);
+
+  /** Whether the clocks show this time for the second time: they went back a moment ago. */
+  const repeated = (time: number, offset: number): boolean => {
+    const before = offsetOf(timezone, time - CLOCK_CHANGE_MINUTES * MINUTE);
+    if (before <= offset) return false;
+    const first = time - (before - offset);
+    return offsetOf(timezone, first) === before;
+  };
+
+  /** When the clocks jumped forward between two moments, if a firing fell into the skipped time. */
+  const skippedFiring = (from: number, to: number): number | undefined => {
+    const before = offsetOf(timezone, from);
+    const after = offsetOf(timezone, to);
+    if (after <= before) return undefined;
+    let low = from;
+    let high = to;
+    while (high - low > MINUTE) {
+      const middle = Math.floor((low + high) / 2 / MINUTE) * MINUTE;
+      if (offsetOf(timezone, middle) === before) low = middle;
+      else high = middle;
+    }
+    for (let clock = high + before; clock < high + after; clock += MINUTE) {
+      if (clockMatches(new Date(clock))) return high;
+    }
+    return undefined;
+  };
 
   return {
-    matches,
+    matches(date: Date): boolean {
+      const offset = offsetOf(timezone, date.getTime());
+      if (!clockMatches(new Date(date.getTime() + offset))) return false;
+      return !(hourSet && timezone !== undefined && repeated(Math.floor(date.getTime() / MINUTE) * MINUTE, offset));
+    },
     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);
+      const limit = after.getTime() + 5 * 366 * DAY_MINUTES * MINUTE;
+      let time = Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE;
+      let previous = time - MINUTE;
+      while (time <= limit) {
+        if (hourSet && timezone !== undefined) {
+          const skipped = skippedFiring(previous, time);
+          if (skipped !== undefined) return new Date(skipped);
+        }
+        previous = time;
+        const offset = offsetOf(timezone, time);
+        const clock = new Date(time + offset);
+        const minutesOfDay = clock.getUTCHours() * 60 + clock.getUTCMinutes();
+        if (!dayMatches(clock)) {
+          // Close to midnight hour by hour: the day may be shorter than its clocks say.
+          const left = DAY_MINUTES - minutesOfDay;
+          time += (timezone === undefined ? left : left > CLOCK_CHANGE_MINUTES ? left - CLOCK_CHANGE_MINUTES : 60 - clock.getUTCMinutes()) * MINUTE;
+        } else if (!hours.has(clock.getUTCHours())) {
+          time += (60 - clock.getUTCMinutes()) * MINUTE;
+        } else if (!minutes.has(clock.getUTCMinutes())) {
+          time += MINUTE;
+        } else if (hourSet && timezone !== undefined && repeated(time, offset)) {
+          time += MINUTE;
         } else {
-          return date;
+          return new Date(time);
         }
       }
       return undefined;

package/library/workflow/index.ts

@@ -20,7 +20,7 @@ export {
   type ProcessNode,
   type ProcessSettings,
 } from "./ProcessDocument";
-export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
+export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, ISO_MOMENT, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
 export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, type InstanceData } from "./paths";
 export {
@@ -42,7 +42,8 @@ export {
 } from "./expressions";
 export { ExpressionSyntaxError, parseExpression, printExpression } from "./expressionSyntax";
 export { durationMs } from "./duration";
-export { parseCron, type CronSchedule } from "./cron";
+export { documentReferences, inputReferences, schemaReferenceKinds, type DocumentReference, type InputReference } from "./references";
+export { isTimeZone, parseCron, type CronSchedule } from "./cron";
 export { processToMermaid } from "./mermaid";
 export { PERSONAL_MASK, maskByMapping, maskBySchema, masksPersonal, personalPaths, personalVariables, readsPersonal } from "./masking";
 export { allTexts, checkLocalizedText, textOf, type LocalizedText } from "./localized";

package/library/workflow/nodeKinds.ts

@@ -1,4 +1,4 @@
-import { parseCron } from "./cron";
+import { isTimeZone, parseCron } from "./cron";
 import { FIELD_NAME, checkFormSpec } from "./formFields";
 import { DATA_PATH } from "./paths";
 import type { NodeKind } from "./ProcessDocument";
@@ -52,11 +52,42 @@ function first(...checks: (string | null)[]): string | null {
   return checks.find((check) => check !== null) ?? null;
 }
 
-/** Five cron fields: minute, hour, day of month, month, day of week. */
-function cron(config: Record<string, unknown>): string | null {
-  const value = config.cron;
-  if (typeof value !== "string") return "config.cron is required";
-  return parseCron(value) === undefined ? "config.cron must be five valid fields: minute hour day month weekday (UTC)" : null;
+/** A moment with its zone: `2026-11-01T09:00:00+03:00`. */
+export const ISO_MOMENT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+
+function moment(config: Record<string, unknown>, key: string): string | null {
+  const value = config[key];
+  if (value === undefined) return null;
+  return typeof value === "string" && ISO_MOMENT.test(value) && !Number.isNaN(Date.parse(value)) ? null : `config.${key} must be a moment with its zone: 2026-11-01T09:00:00+03:00`;
+}
+
+/** A scheduled start: five cron fields (minute, hour, day of month, month, day of week), where and when it runs. */
+function schedule(config: Record<string, unknown>): string | null {
+  const { cron, timezone, from, until, overlap, partitions } = config;
+  if (typeof cron !== "string") return "config.cron is required";
+  if (parseCron(cron) === undefined) return "config.cron must be five valid fields: minute hour day month weekday";
+  if (timezone !== undefined && !isTimeZone(timezone)) return "config.timezone must be an IANA time zone: Europe/Moscow";
+  const period = first(moment(config, "from"), moment(config, "until"), boolean(config, "catchUp"));
+  if (period !== null) return period;
+  if (typeof from === "string" && typeof until === "string" && Date.parse(from) >= Date.parse(until)) return "config.from must be before config.until";
+  if (overlap !== undefined && overlap !== "skip" && overlap !== "queue" && overlap !== "parallel") return "config.overlap must be skip, queue or parallel";
+  if (partitions !== undefined && partitions !== "none" && partitions !== "all") {
+    if (!Array.isArray(partitions) || partitions.length === 0 || partitions.length > 1000 || !partitions.every((item) => typeof item === "string" && item !== "" && item.length <= 200)) return "config.partitions must be none, all or a list of partitions";
+  }
+  return null;
+}
+
+/** An event start; its expressions are checked with the whole document. */
+function eventStart(config: Record<string, unknown>): string | null {
+  const { debounce } = config;
+  if (debounce !== undefined) {
+    if (typeof debounce !== "object" || debounce === null || Array.isArray(debounce)) return "config.debounce must be an object";
+    const { key } = debounce as { key?: unknown };
+    if (key === undefined) return "config.debounce.key is required";
+    const problem = string(debounce as Record<string, unknown>, "window", ISO_DURATION);
+    if (problem !== null) return problem.replace("config.", "config.debounce.");
+  }
+  return first(string(config, "event", DOTTED_KEY), string(config, "delay", ISO_DURATION, false), boolean(config, "ignoreOwn"));
 }
 
 /** A timer: either `duration` (ISO 8601) or `at`, a path to a date in instance data. */
@@ -158,8 +189,32 @@ const fields = { type: "object", properties: { fields: { type: "array", items: {
 
 export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
   { kind: "manualStart", role: "start", check: none, config: object({}) },
-  { kind: "scheduleStart", role: "start", check: cron, config: object({ cron: text }, ["cron"]) },
-  { kind: "eventStart", role: "start", check: (c) => string(c, "event", DOTTED_KEY), config: object({ event: text }, ["event"]) },
+  {
+    kind: "scheduleStart",
+    role: "start",
+    check: schedule,
+    config: object({
+      cron: text,
+      timezone: { type: "string", description: "An IANA time zone; UTC by default" },
+      from: { type: "string", format: "date-time" },
+      until: { type: "string", format: "date-time" },
+      overlap: { enum: ["skip", "queue", "parallel"] },
+      catchUp: flag,
+      partitions: { description: "none, all or a list of partitions", oneOf: [{ enum: ["none", "all"] }, { type: "array", items: text }] },
+    }, ["cron"]),
+  },
+  {
+    kind: "eventStart",
+    role: "start",
+    check: eventStart,
+    config: object({
+      event: text,
+      filter: expression,
+      debounce: object({ key: expression, window: duration }, ["key", "window"]),
+      delay: duration,
+      ignoreOwn: flag,
+    }, ["event"]),
+  },
   {
     kind: "userTask",
     role: "activity",
@@ -218,7 +273,7 @@ export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
     kind: "eventWait",
     role: "activity",
     check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), string(c, "saveTo", FIELD_NAME, false)),
-    config: object({ event: text, correlation: dataPath, saveTo }, ["event"]),
+    config: object({ event: text, correlation: dataPath, saveTo, until: expression }, ["event"]),
   },
   { kind: "exclusiveGateway", role: "gateway", check: none, config: object({}) },
   { kind: "parallelGateway", role: "gateway", check: none, config: object({}) },

package/library/workflow/paths.ts

@@ -10,7 +10,7 @@ export interface InstanceData {
   readonly nodes: Readonly<Record<string, unknown>>;
   /** The data of the event that started or continued the process. */
   readonly event?: unknown;
-  /** How it was started: `{ via, at, actor, eventKey?, cause? }`. */
+  /** How it was started: `{ via, at, actor, eventKey?, cause?, scheduledAt? }`. */
   readonly trigger?: unknown;
   /** `{ id, processKey, version, partition, test }`. */
   readonly run?: unknown;
@@ -31,7 +31,7 @@ export const DATA_PATHS: readonly { readonly path: string; readonly description:
   { path: "$vars.<name>", description: "A variable of the process" },
   { path: "$nodes.<node>.<field>", description: "The result of a passed step" },
   { path: "$event", description: "The data of the event that started or continued the process" },
-  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause? }" },
+  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause?, scheduledAt? }" },
   { path: "$run", description: "This run: { id, processKey, version, partition, test }" },
   { path: "$now", description: "The engine's time" },
   { path: "$item", description: "Inside a loop body: the element of this iteration" },

package/library/workflow/references.ts

@@ -0,0 +1,106 @@
+import { isExpressionNode } from "./expressions";
+import { isPath } from "./paths";
+import type { ProcessDocument } from "./ProcessDocument";
+
+/** One reference in a Tool input or a document: what `x-ref` and `x-ref-keys` of a schema mark. */
+export interface InputReference {
+  readonly kind: string;
+  readonly id: string;
+  /** The area it is looked for in: `x-ref-scope`. */
+  readonly within?: string;
+  /** Where in the input: `/values/status`. */
+  readonly path: string;
+}
+
+/** A reference of a document, and whose it is. */
+export interface DocumentReference extends InputReference {
+  readonly node?: string;
+  readonly variable?: string;
+}
+
+type Json = Record<string, unknown>;
+
+function isObject(value: unknown): value is Json {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Whether a value is known only when the step runs. */
+function isComputed(value: unknown): boolean {
+  return isPath(value) || isExpressionNode(value);
+}
+
+function isId(value: unknown): value is string | number {
+  return (typeof value === "string" && value !== "") || typeof value === "number";
+}
+
+/**
+ * The references in a Tool input by the JSON Schema of the input. A value computed
+ * when the step runs is left out: it is checked then. `x-ref-scope` beginning
+ * with `/` is a JSON Pointer to another field of the input; otherwise it is the area
+ * itself. A reference whose area is computed is left out too.
+ */
+export function inputReferences(schema: unknown, input: unknown): InputReference[] {
+  const out: InputReference[] = [];
+  const within = (source: Json): { readonly known: boolean; readonly value?: string } => {
+    const scope = source["x-ref-scope"];
+    if (typeof scope !== "string") return { known: true };
+    if (!scope.startsWith("/")) return { known: true, value: scope };
+    let current: unknown = input;
+    for (const key of scope.slice(1).split("/")) {
+      current = isObject(current) && Object.hasOwn(current, key) ? current[key] : undefined;
+    }
+    return isId(current) && !isComputed(current) ? { known: true, value: String(current) } : { known: false };
+  };
+  const walk = (source: unknown, value: unknown, path: string): void => {
+    if (!isObject(source) || value === undefined || value === null || isComputed(value)) return;
+    const area = within(source);
+    const add = (kind: string, id: string, at: string) => out.push({ kind, id, ...(area.value === undefined ? {} : { within: area.value }), path: at });
+    if (typeof source["x-ref"] === "string" && isId(value) && area.known) add(source["x-ref"], String(value), path);
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(source.items, item, `${path}/${index}`));
+      return;
+    }
+    if (!isObject(value)) return;
+    if (typeof source["x-ref-keys"] === "string" && area.known) for (const key of Object.keys(value)) add(source["x-ref-keys"], key, `${path}/${key}`);
+    if (isObject(source.properties)) {
+      for (const [key, item] of Object.entries(source.properties)) if (Object.hasOwn(value, key)) walk(item, value[key], `${path}/${key}`);
+    }
+  };
+  walk(schema, input, "");
+  return out;
+}
+
+/** The kinds a schema refers to, whatever the values: each must have an owner. */
+export function schemaReferenceKinds(schema: unknown): string[] {
+  const kinds = new Set<string>();
+  const walk = (source: unknown): void => {
+    if (!isObject(source)) return;
+    for (const key of ["x-ref", "x-ref-keys"]) if (typeof source[key] === "string") kinds.add(source[key]);
+    if (isObject(source.properties)) Object.values(source.properties).forEach(walk);
+    walk(source.items);
+  };
+  walk(schema);
+  return [...kinds];
+}
+
+/**
+ * The references a document holds as literals (WORKFLOW-002 §6.3): in the inputs of
+ * its Tools, by their schemas; the defaults of variables of type `ref`; the processes
+ * it calls. `inputSchemaOf` gives the input schema of a Tool, if it is known.
+ */
+export function documentReferences(document: ProcessDocument, inputSchemaOf: (tool: string) => unknown): DocumentReference[] {
+  const out: DocumentReference[] = [];
+  for (const variable of document.variables ?? []) {
+    if (variable.type === "ref" && typeof variable.ref === "string" && isId(variable.default)) {
+      out.push({ kind: variable.ref, id: String(variable.default), path: "/default", variable: variable.name });
+    }
+  }
+  const handler = document.settings?.errorHandler;
+  if (handler !== undefined) out.push({ kind: "workflow.process", id: handler, path: "/settings/errorHandler" });
+  for (const [node, { kind, config }] of Object.entries(document.nodes)) {
+    if (kind === "callProcess" && typeof config?.process === "string") out.push({ kind: "workflow.process", id: config.process, path: "/process", node });
+    if (kind !== "serviceTask" || typeof config?.tool !== "string") continue;
+    for (const reference of inputReferences(inputSchemaOf(config.tool), config.input)) out.push({ ...reference, node });
+  }
+  return out;
+}

package/library/workflow/validateProcess.ts

@@ -33,6 +33,7 @@ export type ProcessIssueCode =
   | "config_invalid"
   | "unknown_tool"
   | "unknown_process"
+  | "broken_ref"
   | "container_invalid"
   | "flow_across_container"
   | "loop_body"
@@ -451,6 +452,18 @@ function configExpressionProblems(kind: string, config: Json, scope: ExpressionS
     const problem = checkExpression(config.over, scope);
     if (problem) out.push(`config.over: ${problem}`);
   }
+  if (kind === "eventWait" && config.until !== undefined) {
+    const problem = checkExpression(config.until, scope);
+    if (problem) out.push(`config.until: ${problem}`);
+  }
+  if (kind === "eventStart") {
+    // Before an instance exists there is only the event: nothing to read in the input, variables and steps.
+    const before: ExpressionScope = { input: new Set(), vars: new Set(), nodes: new Set(), loop: false };
+    const filter = config.filter === undefined ? null : checkExpression(config.filter, before);
+    if (filter) out.push(`config.filter: ${filter}`);
+    const debounceKey = isObject(config.debounce) ? checkExpression(config.debounce.key, before) : null;
+    if (debounceKey) out.push(`config.debounce.key: ${debounceKey}`);
+  }
   for (const key of ["at", "correlation"]) {
     if (typeof config[key] === "string") {
       const problem = checkPath(config[key], scope);