bazis 0.123.0 → 0.124.0

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

@@ -0,0 +1,49 @@
+import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
+import { WfInstance } from "./WfInstance.model";
+
+/** `tool` calls a service task's Tool; `timer`, `retry` and `schedule` come with their stages. */
+export type JobKind = "tool" | "timer" | "retry" | "schedule";
+
+/**
+ * Deferred work of the worker, created in the same transaction as the waiting
+ * token. Application instances claim it with `FOR UPDATE SKIP LOCKED`.
+ */
+@ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
+@Entity({ table: "bazis_wf_run_jobs" })
+export class WfJob {
+  @UUID({ version: "v7" })
+  id = "";
+
+  @Column({ type: "text" })
+  kind: JobKind = "tool";
+
+  /** `null` for a `schedule` job: its instance does not exist yet. */
+  @Index()
+  @Column({ type: "uuid", nullable: true })
+  instanceId: string | null = null;
+
+  @Index()
+  @Column({ type: "uuid", nullable: true })
+  tokenId: string | null = null;
+
+  /** The version a `schedule` job starts. */
+  @Column({ type: "uuid", nullable: true })
+  versionId: string | null = null;
+
+  @Index()
+  @Column({ type: "datetime" })
+  dueAt = new Date(0);
+
+  @Column({ type: "integer" })
+  attempts = 0;
+
+  /** The worker holds the job until then; if it dies, the job becomes free again. */
+  @Column({ type: "datetime", nullable: true })
+  lockedUntil: Date | null = null;
+
+  @Column({ type: "text", nullable: true })
+  lastError: string | null = null;
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+}

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

@@ -0,0 +1,30 @@
+import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
+import { WfInstance } from "./WfInstance.model";
+
+/** A token waiting for an event: `eventWait` or `boundaryEvent`. Matched by key and correlation. */
+@ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
+@Index(["eventKey", "correlation"])
+@Entity({ table: "bazis_wf_run_subscriptions" })
+export class WfSubscription {
+  @UUID({ version: "v7" })
+  id = "";
+
+  @Column({ type: "uuid" })
+  instanceId = "";
+
+  @Index()
+  @Column({ type: "uuid" })
+  tokenId = "";
+
+  @Column({ type: "text" })
+  eventKey = "";
+
+  @Column({ type: "text", nullable: true })
+  correlation: string | null = null;
+
+  @Column({ type: "text", nullable: true })
+  partition: string | null = null;
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+}

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

@@ -0,0 +1,39 @@
+import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
+import { WfInstance } from "./WfInstance.model";
+
+/**
+ * `active` passes a node, `waiting` waits for a Tool, a task or a join, `done`
+ * moved on, `cancelled` was closed by a cancel, `failed` waits for a retry.
+ */
+export type TokenStatus = "active" | "waiting" | "done" | "cancelled" | "failed";
+
+/** Where execution is. After a parallel gateway an instance has several. Its id is the idempotency key of a Tool call. */
+@ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
+@Index(["instanceId", "status"])
+@Entity({ table: "bazis_wf_run_tokens" })
+export class WfToken {
+  @UUID({ version: "v7" })
+  id = "";
+
+  @Column({ type: "uuid" })
+  instanceId = "";
+
+  @Column({ type: "text" })
+  nodeId = "";
+
+  /** The flow the token came by; `null` on a start node. */
+  @Column({ type: "text", nullable: true })
+  viaFlowId: string | null = null;
+
+  @Column({ type: "text" })
+  status: TokenStatus = "active";
+
+  @Column({ type: "json", nullable: true })
+  output: unknown = null;
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+
+  @Column({ type: "datetime", nullable: true })
+  endedAt: Date | null = null;
+}

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

@@ -0,0 +1,82 @@
+import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { HistoryType } from "../model/WfHistory.model";
+import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
+import type { TokenStatus } from "../model/WfToken.model";
+
+export interface StartInstance {
+  readonly input?: unknown;
+  /** The application's scope: a space, an organization. */
+  readonly partition?: string | null;
+  /** The application's own key of what the instance is about: `order:42`. */
+  readonly businessKey?: string | null;
+  /** On whose behalf the steps run. */
+  readonly actor: WorkflowActor;
+}
+
+export interface InstanceSummary {
+  readonly id: string;
+  readonly processKey: string;
+  readonly version: number;
+  readonly partition: string | null;
+  readonly status: InstanceStatus;
+  readonly businessKey: string | null;
+  readonly startedVia: StartedVia;
+  readonly startedBy: WorkflowActor;
+  readonly error: { readonly node: string; readonly code: string; readonly message: string } | null;
+  readonly createdAt: Date;
+  readonly endedAt: Date | null;
+}
+
+export interface TokenDetails {
+  readonly id: string;
+  readonly nodeId: string;
+  readonly viaFlowId: string | null;
+  readonly status: TokenStatus;
+  readonly output: unknown;
+  readonly createdAt: Date;
+  readonly endedAt: Date | null;
+}
+
+export interface InstanceDetails extends InstanceSummary {
+  readonly input: Record<string, unknown>;
+  readonly vars: Record<string, unknown>;
+  readonly nodes: Record<string, unknown>;
+  /** Every token, oldest first. */
+  readonly tokens: readonly TokenDetails[];
+}
+
+export interface HistoryEntry {
+  readonly id: string;
+  readonly tokenId: string | null;
+  readonly nodeId: string | null;
+  readonly type: HistoryType;
+  readonly data: Record<string, unknown> | null;
+  readonly actor: WorkflowActor | null;
+  readonly at: Date;
+}
+
+export interface InstanceListQuery extends WorkflowPaging {
+  readonly partition?: string;
+  readonly status?: InstanceStatus;
+  readonly processKey?: string;
+  readonly businessKey?: string;
+  readonly startedById?: string;
+}
+
+/**
+ * Runs published versions (WORKFLOW-001 §4). Errors are {@link WorkflowError}:
+ * `not_found`, `archived`, `invalid_input` with the issues, `wrong_status`.
+ */
+export abstract class IWorkflowRuntime {
+  /** Starts the latest version of a process from its manual start. */
+  abstract start(processKey: string, options: StartInstance): Promise<InstanceDetails>;
+  abstract cancel(instanceId: string, options: { readonly reason?: string | null; readonly actor: WorkflowActor }): Promise<InstanceDetails>;
+  /** Retries the failed steps of a `failed` instance. */
+  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>;
+  /** Instances, newest first. */
+  abstract instances(query?: InstanceListQuery): Promise<WorkflowPage<InstanceSummary>>;
+  abstract instance(instanceId: string): Promise<InstanceDetails>;
+  abstract history(instanceId: string): Promise<readonly HistoryEntry[]>;
+}

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

@@ -0,0 +1,167 @@
+import type { 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";
+import type { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+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 type { WfToken } from "../model/WfToken.model";
+import {
+  IWorkflowRuntime,
+  type HistoryEntry,
+  type InstanceDetails,
+  type InstanceListQuery,
+  type InstanceSummary,
+  type StartInstance,
+} from "./IWorkflowRuntime.service";
+
+const STATUSES = new Set(["running", "completed", "cancelled", "failed"]);
+
+export class WorkflowRuntime extends IWorkflowRuntime {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+    private readonly definitions: IWorkflowDefinitions,
+    private readonly validator: WorkflowInputValidator,
+  ) {
+    super();
+  }
+
+  async start(processKey: string, options: StartInstance): Promise<InstanceDetails> {
+    actorOf(options.actor);
+    const partition = optionalText(options.partition, "partition");
+    const businessKey = optionalText(options.businessKey, "businessKey");
+    const version = await this.definitions.latest(processKey);
+    const start = Object.entries(version.document.nodes).find(([, node]) => node.kind === "manualStart");
+    if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
+    const { value, issues } = await this.validator.validate(version.document.input, options.input, { purpose: "input", processKey, partition });
+    if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
+    const id = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor });
+    return await this.instance(id);
+  }
+
+  async cancel(instanceId: string, options: { readonly reason?: string | null; readonly actor: WorkflowActor }): Promise<InstanceDetails> {
+    actorOf(options.actor);
+    const reason = optionalText(options.reason, "reason", 1000);
+    if (!isUuid(instanceId)) throw notFound(instanceId);
+    const done = await this.engine.inStep(instanceId, async (step) => {
+      if (step.instance.status !== "running" && step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Instance is ${step.instance.status}`);
+      await this.engine.cancel(step, reason, options.actor);
+      return true;
+    });
+    if (done === null) throw notFound(instanceId);
+    return await this.instance(instanceId);
+  }
+
+  async retry(instanceId: string, options: { readonly actor: WorkflowActor }): Promise<InstanceDetails> {
+    actorOf(options.actor);
+    if (!isUuid(instanceId)) throw notFound(instanceId);
+    const done = await this.engine.inStep(instanceId, async (step) => {
+      if (step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Only a failed instance is retried; this one is ${step.instance.status}`);
+      await this.engine.retry(step, options.actor);
+      return true;
+    });
+    if (done === null) throw notFound(instanceId);
+    return await this.instance(instanceId);
+  }
+
+  async completeToken(tokenId: string, output: unknown, actor: WorkflowActor): Promise<InstanceDetails> {
+    actorOf(actor);
+    if (!isUuid(tokenId)) throw new WorkflowError("not_found", `Token ${tokenId} does not exist`);
+    const token = await this.db.tokens.asNoTracking().firstOrDefault((t) => t.id.eq(tokenId));
+    if (!token) throw new WorkflowError("not_found", `Token ${tokenId} does not exist`);
+    const done = await this.engine.inStep(token.instanceId, async (step) => {
+      const node = step.graph.document.nodes[token.nodeId];
+      const current = step.tokens.find((t) => t.id === tokenId);
+      if (node?.kind !== "userTask" || !current || current.status !== "waiting" || step.instance.status !== "running") {
+        throw new WorkflowError("wrong_status", "The token does not wait for a task");
+      }
+      const { value, issues } = await this.validator.validate(node.config?.form as FormSpec | undefined, output, { purpose: "task", processKey: step.instance.processKey, partition: step.instance.partition });
+      if (issues.length > 0) throw new WorkflowError("invalid_input", "The task form is invalid", issues);
+      await this.engine.complete(step, tokenId, value, actor);
+      return true;
+    });
+    if (done === null) throw notFound(token.instanceId);
+    return await this.instance(token.instanceId);
+  }
+
+  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");
+    let source = this.db.instances.asNoTracking();
+    if (query.partition !== undefined) source = source.where((i) => i.partition.eq(query.partition!));
+    if (query.status !== undefined) source = source.where((i) => i.status.eq(query.status!));
+    if (query.processKey !== undefined) source = source.where((i) => i.processKey.eq(query.processKey!));
+    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!));
+    const total = await source.count();
+    const rows = await source.orderByDescending((i) => i.id).skip(offset).take(limit).toList();
+    return { items: rows.map(summaryOf), total };
+  }
+
+  async instance(instanceId: string): Promise<InstanceDetails> {
+    if (!isUuid(instanceId)) throw notFound(instanceId);
+    const row = await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(instanceId));
+    if (!row) throw notFound(instanceId);
+    const tokens = await this.db.tokens.asNoTracking().where((t) => t.instanceId.eq(instanceId)).orderBy((t) => t.id).toList();
+    return { ...summaryOf(row), input: row.input, vars: row.vars, nodes: row.nodes, tokens: tokens.map(tokenOf) };
+  }
+
+  async history(instanceId: string): Promise<readonly HistoryEntry[]> {
+    if (!isUuid(instanceId)) throw notFound(instanceId);
+    const exists = await this.db.instances.asNoTracking().where((i) => i.id.eq(instanceId)).count();
+    if (exists === 0) throw notFound(instanceId);
+    const rows = await this.db.history.asNoTracking().where((h) => h.instanceId.eq(instanceId)).orderBy((h) => h.id).toList();
+    return rows.map(historyOf);
+  }
+}
+
+function notFound(instanceId: string): WorkflowError {
+  return new WorkflowError("not_found", `Instance ${instanceId} does not exist`);
+}
+
+function actorOf(actor: WorkflowActor): void {
+  if (typeof actor !== "object" || actor === null || (actor.kind !== "user" && actor.kind !== "system") || typeof actor.id !== "string" || actor.id === "" || actor.id.length > 200) {
+    throw new WorkflowError("invalid_input", "actor must be { kind: \"user\" | \"system\", id }");
+  }
+}
+
+function optionalText(value: unknown, name: string, max = 200): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || value.length > max) throw new WorkflowError("invalid_input", `${name} must be a string up to ${max} characters`);
+  return value;
+}
+
+function summaryOf(row: WfInstance): InstanceSummary {
+  return {
+    id: row.id,
+    processKey: row.processKey,
+    version: row.version,
+    partition: row.partition,
+    status: row.status,
+    businessKey: row.businessKey,
+    startedVia: row.startedVia,
+    startedBy: { kind: row.startedByKind, id: row.startedById },
+    error: row.error,
+    createdAt: row.createdAt,
+    endedAt: row.endedAt,
+  };
+}
+
+function tokenOf(row: WfToken) {
+  return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
+}
+
+function historyOf(row: WfHistory): HistoryEntry {
+  return {
+    id: row.id,
+    tokenId: row.tokenId,
+    nodeId: row.nodeId,
+    type: row.type,
+    data: row.data,
+    actor: row.actorId === null ? null : { kind: row.actorKind === "system" ? "system" : "user", id: row.actorId },
+    at: row.at,
+  };
+}

package/library/workflow/ProcessDocument.ts

@@ -0,0 +1,94 @@
+import type { FormSpec } from "./formFields";
+
+/**
+ * A process document: the framework's own JSON, not BPMN XML (a designer may
+ * render BPMN from it). One object holds the process input (`input`), the graph
+ * (`nodes`, `flows`) and the canvas layout (`diagram`).
+ */
+export const PROCESS_SCHEMA_VERSION = "bazis.workflow/v1";
+
+/** The node kinds of version 1; closed: a new kind comes with a new document version. */
+export type NodeKind =
+  | "manualStart"
+  | "scheduleStart"
+  | "eventStart"
+  | "userTask"
+  | "serviceTask"
+  | "timerCatch"
+  | "eventWait"
+  | "exclusiveGateway"
+  | "parallelGateway"
+  | "boundaryError"
+  | "boundaryTimer"
+  | "boundaryEvent"
+  | "end";
+
+export interface ProcessNode {
+  readonly kind: NodeKind;
+  readonly title: string;
+  /** Boundary nodes only: the step the node is attached to. */
+  readonly attachedTo?: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+
+export interface ProcessFlow {
+  readonly source: string;
+  readonly target: string;
+  readonly title?: string;
+  /** Condition of a flow that leaves an exclusive gateway. */
+  readonly condition?: Condition;
+  /** The flow an exclusive gateway takes when no condition holds. */
+  readonly isDefault?: boolean;
+}
+
+/** Comparison operators of conditions. */
+export type ConditionOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "contains" | "empty" | "notEmpty";
+
+/**
+ * A condition: a tree of `all` / `any` / `not` and comparisons. `path` addresses
+ * instance data: `$input.<field>`, `$vars.<name>`, `$nodes.<node>.<field>`.
+ */
+export type Condition =
+  | { readonly all: readonly Condition[] }
+  | { readonly any: readonly Condition[] }
+  | { readonly not: Condition }
+  | { readonly path: string; readonly op: ConditionOp; readonly value?: unknown };
+
+export interface Bounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Canvas layout: stored and returned, never read by the engine. */
+export interface ProcessDiagram {
+  readonly shapes: Readonly<Record<string, Bounds>>;
+  readonly edges: Readonly<Record<string, { readonly waypoints: readonly Point[] }>>;
+}
+
+export interface ProcessDocument {
+  readonly schemaVersion: typeof PROCESS_SCHEMA_VERSION;
+  /** Fields the process starts with; without them it starts with no data. */
+  readonly input?: FormSpec;
+  readonly nodes: Readonly<Record<string, ProcessNode>>;
+  readonly flows: Readonly<Record<string, ProcessFlow>>;
+  readonly diagram?: ProcessDiagram;
+}
+
+/** A new process: a manual start leading straight to the end. It already passes validation. */
+export function emptyProcess(): ProcessDocument {
+  return {
+    schemaVersion: PROCESS_SCHEMA_VERSION,
+    nodes: {
+      Start: { kind: "manualStart", title: "Start" },
+      End: { kind: "end", title: "End" },
+    },
+    flows: { StartToEnd: { source: "Start", target: "End" } },
+  };
+}

package/library/workflow/conditions.ts

@@ -0,0 +1,44 @@
+import type { Condition } from "./ProcessDocument";
+import { isPath, readPath, type InstanceData } from "./paths";
+
+/** Evaluates a flow condition. Pure: no calls, no side effects. */
+export function evaluateCondition(condition: Condition, data: InstanceData): boolean {
+  if ("all" in condition) return condition.all.every((item) => evaluateCondition(item, data));
+  if ("any" in condition) return condition.any.some((item) => evaluateCondition(item, data));
+  if ("not" in condition) return !evaluateCondition(condition.not, data);
+  const actual = readPath(data, condition.path);
+  const expected = isPath(condition.value) ? readPath(data, condition.value) : condition.value;
+  switch (condition.op) {
+    case "eq": return same(actual, expected);
+    case "ne": return !same(actual, expected);
+    case "gt": return compare(actual, expected, (a, b) => a > b);
+    case "gte": return compare(actual, expected, (a, b) => a >= b);
+    case "lt": return compare(actual, expected, (a, b) => a < b);
+    case "lte": return compare(actual, expected, (a, b) => a <= b);
+    case "in": return Array.isArray(expected) && expected.some((item) => same(actual, item));
+    case "contains":
+      if (typeof actual === "string") return typeof expected === "string" && actual.includes(expected);
+      return Array.isArray(actual) && actual.some((item) => same(item, expected));
+    case "empty": return isEmpty(actual);
+    case "notEmpty": return !isEmpty(actual);
+  }
+}
+
+function same(a: unknown, b: unknown): boolean {
+  if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return Number(a) === Number(b);
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Numbers compare as numbers (a decimal arrives as a string), other strings as strings (ISO dates compare right). */
+function compare(a: unknown, b: unknown, test: (a: number | string, b: number | string) => boolean): boolean {
+  if (a === null || a === undefined || b === null || b === undefined) return false;
+  const na = Number(a), nb = Number(b);
+  if (typeof a !== "boolean" && typeof b !== "boolean" && a !== "" && b !== "" && Number.isFinite(na) && Number.isFinite(nb)) return test(na, nb);
+  return typeof a === "string" && typeof b === "string" ? test(a, b) : false;
+}
+
+function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined || value === "") return true;
+  if (Array.isArray(value)) return value.length === 0;
+  return typeof value === "object" && Object.keys(value).length === 0;
+}

package/library/workflow/duration.ts

@@ -0,0 +1,10 @@
+import { ISO_DURATION } from "./nodeKinds";
+
+/** Milliseconds of an ISO 8601 duration without months and years (`P2D`, `PT1H30M`); `undefined` if it is not one. */
+export function durationMs(value: string): number | undefined {
+  const match = ISO_DURATION.exec(value);
+  if (!match) return undefined;
+  const number = (part: string | undefined) => (part === undefined ? 0 : Number.parseInt(part, 10));
+  const weeks = number(match[1]), days = number(match[2]), hours = number(match[4]), minutes = number(match[5]), seconds = number(match[6]);
+  return ((((weeks * 7 + days) * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
+}

package/library/workflow/formFields.ts

@@ -0,0 +1,112 @@
+/** Field types of a process input and of a task form. */
+export type FormFieldType = "string" | "text" | "number" | "integer" | "boolean" | "date" | "datetime" | "enum";
+
+export interface FormField {
+  /** The key in the value: `amount`, `reason`. */
+  readonly code: string;
+  readonly type: FormFieldType;
+  readonly title?: string;
+  readonly required?: boolean;
+  /** Allowed values of an `enum` field. */
+  readonly values?: readonly (string | number)[];
+}
+
+/** The fields of a process input or a task form. */
+export interface FormSpec {
+  readonly fields: readonly FormField[];
+}
+
+/** One problem of a value: which field and why. */
+export interface FormIssue {
+  readonly field: string;
+  readonly code: "required" | "type" | "enum" | "unknown";
+  readonly message: string;
+}
+
+const TYPES = new Set<FormFieldType>(["string", "text", "number", "integer", "boolean", "date", "datetime", "enum"]);
+const CODE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_FIELDS = 200;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Checks the shape of a form spec; returns a problem or `null`. `at` names it in the text. */
+export function checkFormSpec(value: unknown, at: string): string | null {
+  if (!isObject(value) || !Array.isArray(value.fields)) return `${at} must be an object with a fields list`;
+  if (value.fields.length > MAX_FIELDS) return `${at} has more than ${MAX_FIELDS} fields`;
+  const seen = new Set<string>();
+  for (const [index, field] of value.fields.entries()) {
+    const where = `${at}.fields[${index}]`;
+    if (!isObject(field)) return `${where} must be an object`;
+    if (typeof field.code !== "string" || !CODE.test(field.code) || field.code === "__proto__") return `${where}.code is invalid`;
+    if (seen.has(field.code)) return `${where}.code ${field.code} is repeated`;
+    seen.add(field.code);
+    if (typeof field.type !== "string" || !TYPES.has(field.type as FormFieldType)) return `${where}.type must be one of ${[...TYPES].join(", ")}`;
+    if (field.title !== undefined && (typeof field.title !== "string" || field.title.length > 200)) return `${where}.title must be up to 200 characters`;
+    if (field.required !== undefined && typeof field.required !== "boolean") return `${where}.required must be a boolean`;
+    if (field.type === "enum") {
+      if (!Array.isArray(field.values) || field.values.length === 0 || !field.values.every((item) => typeof item === "string" || typeof item === "number")) {
+        return `${where}.values must be a non-empty list of strings or numbers`;
+      }
+    } else if (field.values !== undefined) {
+      return `${where}.values is only for enum fields`;
+    }
+  }
+  return null;
+}
+
+/** The field codes of a form spec. */
+export function formFieldCodes(spec: FormSpec): string[] {
+  return spec.fields.map((field) => field.code);
+}
+
+/**
+ * Checks a value against a form spec: required fields, types, enum values and
+ * unknown fields. Returns the value with only the declared fields and every issue.
+ * Without a spec the form takes no data: any field is unknown.
+ */
+export function validateForm(spec: FormSpec | undefined, value: unknown): { readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] } {
+  const issues: FormIssue[] = [];
+  const source = value === undefined || value === null ? {} : value;
+  if (!isObject(source)) return { value: {}, issues: [{ field: "", code: "type", message: "value must be an object" }] };
+  const fields = spec?.fields ?? [];
+  const declared = new Set(fields.map((field) => field.code));
+  for (const key of Object.keys(source)) {
+    if (!declared.has(key)) issues.push({ field: key, code: "unknown", message: `field ${key} is not declared` });
+  }
+  const out: Record<string, unknown> = {};
+  for (const field of fields) {
+    const item = Object.hasOwn(source, field.code) ? source[field.code] : undefined;
+    if (item === undefined || item === null || item === "") {
+      if (field.required === true) issues.push({ field: field.code, code: "required", message: `field ${field.code} is required` });
+      continue;
+    }
+    const problem = checkType(field, item);
+    if (problem) issues.push({ field: field.code, ...problem });
+    else out[field.code] = item;
+  }
+  return { value: out, issues };
+}
+
+function checkType(field: FormField, value: unknown): { code: "type" | "enum"; message: string } | null {
+  const wrong = (expected: string) => ({ code: "type" as const, message: `field ${field.code} must be ${expected}` });
+  switch (field.type) {
+    case "string":
+    case "text":
+      return typeof value === "string" ? null : wrong("a string");
+    case "number":
+      return typeof value === "number" && Number.isFinite(value) ? null : wrong("a number");
+    case "integer":
+      return Number.isSafeInteger(value) ? null : wrong("an integer");
+    case "boolean":
+      return typeof value === "boolean" ? null : wrong("true or false");
+    case "date":
+      return typeof value === "string" && DATE.test(value) && !Number.isNaN(Date.parse(value)) ? null : wrong("a date YYYY-MM-DD");
+    case "datetime":
+      return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? null : wrong("an ISO 8601 date and time");
+    case "enum":
+      return (field.values ?? []).includes(value as string | number) ? null : { code: "enum", message: `field ${field.code} must be one of ${(field.values ?? []).join(", ")}` };
+  }
+}

package/library/workflow/index.ts

@@ -0,0 +1,24 @@
+/**
+ * The process document format `bazis.workflow/v1` (WORKFLOW-001 §2): types,
+ * node kinds, validation, data paths and conditions. Pure functions without DI
+ * or a database: usable by a designer, a CLI or a browser.
+ */
+export {
+  PROCESS_SCHEMA_VERSION,
+  emptyProcess,
+  type Bounds,
+  type Condition,
+  type ConditionOp,
+  type NodeKind,
+  type Point,
+  type ProcessDiagram,
+  type ProcessDocument,
+  type ProcessFlow,
+  type ProcessNode,
+} from "./ProcessDocument";
+export { NODE_KINDS, nodeKindOf, ISO_DURATION, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
+export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
+export { DATA_PATH, isPath, readPath, resolveInput, type InstanceData } from "./paths";
+export { evaluateCondition } from "./conditions";
+export { durationMs } from "./duration";
+export { checkFormSpec, formFieldCodes, validateForm, type FormField, type FormFieldType, type FormIssue, type FormSpec } from "./formFields";