bazis 0.126.0 → 0.128.0

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

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

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

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

package/core/workflow/testing/index.ts

@@ -0,0 +1,162 @@
+import { DI } from "../../di";
+import { startTestApp, type TestApp, type TestAppOptions } from "../../testing";
+import { durationMs } from "../../../library/workflow";
+import { WorkflowClock } from "../contracts/WorkflowClock";
+import type { WorkflowActor } from "../contracts/types";
+import { WorkflowJobs } from "../runtime_module/internal/WorkflowJobs";
+import { IWorkflowRuntime, type EmitOptions, type EmitResult, type HistoryEntry, type InstanceDetails, type StartInstance } from "../runtime_module/services/IWorkflowRuntime.service";
+import { TasksDbContext } from "../tasks_module/model/Tasks.dbContext";
+import { IWorkflowTasks } from "../tasks_module/services/IWorkflowTasks.service";
+
+/** Rounds of `drain` before it gives up: a process that keeps creating due jobs never settles. */
+const MAX_ROUNDS = 1000;
+const BATCH = 50;
+const TEST_ACTOR: WorkflowActor = { kind: "system", id: "test" };
+
+/** A clock that stands still until the test moves it (WORKFLOW-001 §14). */
+export class ManualWorkflowClock extends WorkflowClock {
+  override readonly manual = true;
+  private current: number;
+
+  constructor(start: Date | string = new Date()) {
+    super();
+    this.current = toTime(start, "now");
+  }
+
+  now(): Date {
+    return new Date(this.current);
+  }
+
+  /** Moves the clock forward by an ISO duration (`PT2H`, `P1D`) or milliseconds. */
+  advance(by: string | number): Date {
+    const ms = typeof by === "number" ? by : durationMs(by);
+    if (ms === undefined || !Number.isFinite(ms) || ms < 0) throw new Error(`advance takes an ISO duration without months and years or milliseconds ≥ 0, not ${JSON.stringify(by)}`);
+    this.current += ms;
+    return this.now();
+  }
+
+  /** Moves the clock forward to a moment. */
+  set(to: Date | string): Date {
+    const time = toTime(to, "set");
+    if (time < this.current) throw new Error(`The workflow clock only moves forward: it is ${this.now().toISOString()}`);
+    this.current = time;
+    return this.now();
+  }
+}
+
+export interface TestWorkflowOptions extends TestAppOptions {
+  /** Where the workflow clock starts; the current time by default. */
+  readonly now?: Date | string;
+  /** On whose behalf `start`, `emit` and `complete` act; `{ kind: "system", id: "test" }` by default. */
+  readonly actor?: WorkflowActor;
+}
+
+/** A started application whose processes run only when the test says so. */
+export interface TestWorkflow {
+  readonly app: TestApp;
+  readonly clock: ManualWorkflowClock;
+  now(): Date;
+  /** Starts the latest version of a process from its manual start; jobs wait for {@link drain}. */
+  start(processKey: string, options?: Partial<StartInstance>): Promise<InstanceDetails>;
+  emit(eventKey: string, payload?: unknown, options?: EmitOptions): Promise<EmitResult>;
+  /** Completes the user task waiting at `nodeId` (through its task when the Tasks part is there). */
+  complete(instanceId: string, nodeId: string, output?: unknown, actor?: WorkflowActor): Promise<InstanceDetails>;
+  /** Plans scheduled starts and runs every job due by the workflow clock until none is left; returns how many ran. */
+  drain(): Promise<number>;
+  /** Moves the clock forward (ISO duration or milliseconds), then {@link drain}. */
+  advance(by: string | number): Promise<number>;
+  instance(instanceId: string): Promise<InstanceDetails>;
+  history(instanceId: string): Promise<readonly HistoryEntry[]>;
+  stop(): Promise<void>;
+}
+
+/**
+ * Starts the application like `startTestApp`, with a {@link ManualWorkflowClock}
+ * and no background worker: jobs run only in `drain`, so a test of a process is
+ * deterministic. Needs PostgreSQL, as the workflow module does.
+ *
+ * ```ts
+ * const wf = await testWorkflow(AppModule, { now: "2026-11-02T09:00:00Z" });
+ * try {
+ *   const order = await wf.start("order-approval", { input: { amount: 5000 } });
+ *   await wf.drain();
+ *   await wf.complete(order.id, "approve", { approved: true });
+ *   await wf.advance("PT2H");
+ *   expect((await wf.instance(order.id)).status).toBe("completed");
+ * } finally {
+ *   await wf.stop();
+ * }
+ * ```
+ */
+export async function testWorkflow(root: Parameters<typeof startTestApp>[0], options: TestWorkflowOptions = {}): Promise<TestWorkflow> {
+  const { now, actor = TEST_ACTOR, overrides = [], ...appOptions } = options;
+  const clock = new ManualWorkflowClock(now);
+  const app = await startTestApp(root, { ...appOptions, overrides: [...overrides, DI.singleton(DI.valueProvider(WorkflowClock, clock))] });
+  const failures: unknown[] = [];
+  const jobs = new WorkflowJobs(app.container, (message, error, fields) => failures.push({ message, error, ...fields }));
+  const signal = new AbortController().signal;
+
+  const inScope = async <T>(work: (scope: ReturnType<TestApp["container"]["createScope"]>) => Promise<T>): Promise<T> => {
+    const scope = app.container.createScope();
+    try {
+      return await work(scope);
+    } finally {
+      await scope.dispose();
+    }
+  };
+
+  const drain = async (): Promise<number> => {
+    await jobs.reconcile();
+    let ran = 0;
+    for (let round = 0; round < MAX_ROUNDS; round += 1) {
+      const due = await jobs.claim(BATCH);
+      if (due.length === 0) return ran;
+      for (const job of due) await jobs.run(job, signal);
+      ran += due.length;
+      // A failure outside a Tool (a failing Tool is a step result) is a bug the test should see.
+      if (failures.length > 0) {
+        const found = failures.splice(0);
+        throw new AggregateError(found.map((failure) => (failure as { error: unknown }).error), `drain: ${found.length} job(s) failed outside their Tools: ${found.map((failure) => { const { message, error } = failure as { message: string; error: unknown }; return `${message}: ${error instanceof Error ? error.message : String(error)}`; }).join("; ")}`);
+      }
+    }
+    throw new Error(`drain did not settle after ${MAX_ROUNDS} rounds: a process keeps creating due jobs`);
+  };
+
+  return {
+    app,
+    clock,
+    now: () => clock.now(),
+    start: (processKey, start = {}) => inScope((scope) => scope.resolve(IWorkflowRuntime).start(processKey, { ...start, actor: start.actor ?? actor })),
+    emit: (eventKey, payload, emitOptions = {}) => inScope((scope) => scope.resolve(IWorkflowRuntime).emit(eventKey, payload, { ...emitOptions, actor: emitOptions.actor ?? actor })),
+    complete: (instanceId, nodeId, output = {}, by = actor) => inScope(async (scope) => {
+      const runtime = scope.resolve(IWorkflowRuntime);
+      const instance = await runtime.instance(instanceId);
+      const token = instance.tokens.find((t) => t.nodeId === nodeId && t.status === "waiting");
+      if (!token) {
+        const waiting = instance.tokens.filter((t) => t.status === "waiting").map((t) => t.nodeId);
+        throw new Error(`No step waits at ${nodeId} in instance ${instanceId} (${instance.status}); waiting: ${waiting.length === 0 ? "none" : waiting.join(", ")}`);
+      }
+      const tasks = scope.tryResolve(IWorkflowTasks);
+      const task = tasks === undefined ? undefined : await scope.resolve(TasksDbContext).tasks.asNoTracking().firstOrDefault((t) => t.tokenId.eq(token.id).and(t.status.in(["open", "claimed"])));
+      if (tasks !== undefined && task) {
+        await tasks.complete(task.id, output, by);
+        return await runtime.instance(instanceId);
+      }
+      return await runtime.completeToken(token.id, output, by);
+    }),
+    drain,
+    advance: async (by) => {
+      clock.advance(by);
+      return await drain();
+    },
+    instance: (instanceId) => inScope((scope) => scope.resolve(IWorkflowRuntime).instance(instanceId)),
+    history: (instanceId) => inScope((scope) => scope.resolve(IWorkflowRuntime).history(instanceId)),
+    stop: () => app.stop(),
+  };
+}
+
+function toTime(value: Date | string, what: string): number {
+  const time = value instanceof Date ? value.getTime() : Date.parse(value);
+  if (!Number.isFinite(time)) throw new Error(`The workflow clock ${what} must be a date, not ${JSON.stringify(value)}`);
+  return time;
+}

package/library/terminal/messages.ts

@@ -32,6 +32,8 @@ const NOUNS_EN = {
   change: ["change", "changes", "changes"],
   part: ["part", "parts", "parts"],
   context: ["database context", "database contexts", "database contexts"],
+  process: ["process", "processes", "processes"],
+  node: ["node", "nodes", "nodes"],
 } as const satisfies Record<string, Forms>;
 
 export type Noun = keyof typeof NOUNS_EN;
@@ -60,6 +62,8 @@ const NOUNS_RU: Record<Noun, Forms> = {
   change: ["изменение", "изменения", "изменений"],
   part: ["часть", "части", "частей"],
   context: ["контекст базы данных", "контекста базы данных", "контекстов базы данных"],
+  process: ["процесс", "процесса", "процессов"],
+  node: ["узел", "узла", "узлов"],
 };
 
 /** Genitive after «из N»: «из 1 подключения», «из 3 подключений», «из 21 подключения». */
@@ -239,6 +243,18 @@ const en = {
     needsCache: "this module caches: pass runApp(AppModule, { cache: memory() })",
     keptOnFailure: "scaffold files were kept — fix the error and run bazis codegen",
   },
+  workflow: {
+    app: "app",
+    section: "PROCESSES IN CODE",
+    none: "no module declares processes — add one with bazis g process <Name> --module <Name>",
+    passed: (count: number) => `${count} ${formEn(count, NOUNS_EN.process)} checked`,
+    failed: (count: number) => `process check failed · ${count} ${formEn(count, NOUNS_EN.error)}`,
+    fix: "fix the documents or the Tools: the application refuses to start with these errors",
+    processKind: "process",
+    processCreated: (name: string) => `process ${name} is generated`,
+    processPlanned: (name: string) => `process ${name} is planned`,
+    processRegistered: (host: string) => `listed in processes of ${host}`,
+  },
   errors: {
     unknown: "Use bazis --help to list commands and options.",
     bunTooOld: (required: string, actual: string) => `bazis needs Bun ${required.startsWith(">=") ? `${required.slice(2).trim()} or newer` : required}; this is Bun ${actual}.`,
@@ -404,6 +420,18 @@ const ru: Messages = {
     needsCache: "модуль кэширует: передайте runApp(AppModule, { cache: memory() })",
     keptOnFailure: "файлы модуля оставлены — исправьте ошибку и запустите bazis codegen",
   },
+  workflow: {
+    app: "приложение",
+    section: "ПРОЦЕССЫ В КОДЕ",
+    none: "ни один модуль не объявляет процессы — добавьте процесс: bazis g process <Name> --module <Name>",
+    passed: (count) => `процессы в порядке · ${count} ${formRu(count, NOUNS_RU.process)}`,
+    failed: (count) => `проверка процессов не прошла · ${count} ${formRu(count, NOUNS_RU.error)}`,
+    fix: "исправьте документы или Tools: с этими ошибками приложение не запустится",
+    processKind: "процесс",
+    processCreated: (name) => `процесс ${name} создан`,
+    processPlanned: (name) => `процесс ${name} запланирован`,
+    processRegistered: (host) => `добавлен в processes модуля ${host}`,
+  },
   errors: {
     unknown: "Список команд и опций: bazis --help.",
     bunTooOld: (required, actual) => `bazis нужен Bun ${required.startsWith(">=") ? `${required.slice(2).trim()} или новее` : required}, а запущен Bun ${actual}.`,

package/library/terminal/screen.ts

@@ -58,6 +58,7 @@ export const MODE = Object.freeze({
   new: ["#ff2ee6", "#7b61ff"] as readonly string[],
   gen: ["#c77dff", "#ff2ee6"] as readonly string[],
   codegen: ["#00f0ff", "#c77dff"] as readonly string[],
+  workflow: ["#3dff7a", "#ffd60a"] as readonly string[],
 });
 
 /**

package/library/workflow/index.ts

@@ -22,4 +22,5 @@ export { DATA_PATH, isPath, readPath, resolveInput, type InstanceData } from "./
 export { evaluateCondition } from "./conditions";
 export { durationMs } from "./duration";
 export { parseCron, type CronSchedule } from "./cron";
+export { processToMermaid } from "./mermaid";
 export { checkFormSpec, formFieldCodes, validateForm, type FormField, type FormFieldType, type FormIssue, type FormSpec } from "./formFields";

package/library/workflow/mermaid.ts

@@ -0,0 +1,87 @@
+import type { Condition, NodeKind, ProcessDocument } from "./ProcessDocument";
+
+/** Words Mermaid reads as syntax: such node ids are renamed. */
+const RESERVED = new Set(["end", "graph", "flowchart", "subgraph", "style", "class", "classdef", "click", "default", "linkstyle", "direction"]);
+
+const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
+  manualStart: ["([", "])"],
+  scheduleStart: ["([", "])"],
+  eventStart: ["([", "])"],
+  end: ["((", "))"],
+  userTask: ["[", "]"],
+  serviceTask: ["[[", "]]"],
+  timerCatch: ["{{", "}}"],
+  eventWait: ["{{", "}}"],
+  exclusiveGateway: ["{", "}"],
+  parallelGateway: ["{", "}"],
+  boundaryError: ["((", "))"],
+  boundaryTimer: ["((", "))"],
+  boundaryEvent: ["((", "))"],
+};
+
+/**
+ * A process as a Mermaid `flowchart` (WORKFLOW-001 §14): starts are stadiums,
+ * Tool steps subroutines, tasks rectangles, waits hexagons, gateways rhombi,
+ * ends and boundary events circles. A boundary event hangs on its step by a
+ * dotted link. Labels show the node kind's detail: the Tool, the cron, the
+ * duration, the event key; flows show their title or condition.
+ */
+export function processToMermaid(document: ProcessDocument, direction: "LR" | "TB" = "LR"): string {
+  const ids = new Map<string, string>();
+  const used = new Set<string>();
+  const idOf = (nodeId: string): string => {
+    const known = ids.get(nodeId);
+    if (known !== undefined) return known;
+    let id = /^[A-Za-z][A-Za-z0-9_]*$/.test(nodeId) && !RESERVED.has(nodeId.toLowerCase()) ? nodeId : `n_${nodeId.replace(/[^A-Za-z0-9_]/g, "_")}`;
+    while (used.has(id)) id = `${id}_`;
+    used.add(id);
+    ids.set(nodeId, id);
+    return id;
+  };
+  const lines = [`flowchart ${direction}`];
+  for (const [nodeId, node] of Object.entries(document.nodes)) {
+    const [open, close] = SHAPES[node.kind] ?? ["[", "]"];
+    const detail = detailOf(node.kind, node.config ?? {});
+    lines.push(`  ${idOf(nodeId)}${open}"${label(node.title || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}"${close}`);
+  }
+  for (const [nodeId, node] of Object.entries(document.nodes)) {
+    if (node.attachedTo !== undefined && document.nodes[node.attachedTo] !== undefined) lines.push(`  ${idOf(node.attachedTo)} -.- ${idOf(nodeId)}`);
+  }
+  for (const flow of Object.values(document.flows)) {
+    if (document.nodes[flow.source] === undefined || document.nodes[flow.target] === undefined) continue;
+    const text = flow.title ?? (flow.condition !== undefined ? conditionText(flow.condition) : flow.isDefault === true ? "default" : undefined);
+    lines.push(`  ${idOf(flow.source)} -->${text === undefined ? "" : `|"${label(text)}"|`} ${idOf(flow.target)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function detailOf(kind: NodeKind, config: Readonly<Record<string, unknown>>): string | undefined {
+  const text = (value: unknown) => (typeof value === "string" && value !== "" ? value : undefined);
+  switch (kind) {
+    case "serviceTask": return text(config.tool);
+    case "scheduleStart": return text(config.cron);
+    case "eventStart":
+    case "eventWait":
+    case "boundaryEvent": return text(config.event);
+    case "timerCatch":
+    case "boundaryTimer": return text(config.duration) ?? (text(config.at) === undefined ? undefined : `at ${config.at}`);
+    case "boundaryError": return text(config.errorCode);
+    case "userTask": {
+      const assignee = config.assignee as { role?: unknown; user?: unknown } | undefined;
+      return assignee === undefined ? undefined : text(assignee.role) !== undefined ? `role ${assignee.role}` : text(assignee.user) === undefined ? undefined : `user ${assignee.user}`;
+    }
+    default: return undefined;
+  }
+}
+
+function conditionText(condition: Condition): string {
+  if ("all" in condition) return condition.all.map(conditionText).join(" and ");
+  if ("any" in condition) return condition.any.map(conditionText).join(" or ");
+  if ("not" in condition) return `not (${conditionText(condition.not)})`;
+  return condition.op === "empty" || condition.op === "notEmpty" ? `${condition.path} ${condition.op}` : `${condition.path} ${condition.op} ${JSON.stringify(condition.value)}`;
+}
+
+/** Text inside a quoted Mermaid label: quotes and markup are entities. */
+function label(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "#quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.126.0",
+  "version": "0.128.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",
@@ -44,6 +44,7 @@
     "./core/testing": "./core/testing/index.ts",
     "./core/websocket": "./core/websocket/index.ts",
     "./core/workflow": "./core/workflow/index.ts",
+    "./core/workflow/testing": "./core/workflow/testing/index.ts",
     "./library/boundary": "./library/boundary/index.ts",
     "./library/http-client": "./library/http-client/index.ts",
     "./library/jsonapi": "./library/jsonapi/index.ts",