bazis 0.131.0 → 0.132.0

package/cli/templates/process.ts

@@ -14,7 +14,7 @@ export const ${process.module}Process = defineProcess({
   key: "${process.folder}",
   title: "${title}",
   document: {
-    schemaVersion: "bazis.workflow/v1",
+    schemaVersion: "bazis.workflow/v2",
     nodes: {
       Start: { kind: "manualStart", title: "Start" },
       End: { kind: "end", title: "End" },

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.131.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.132.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/workflow/{runtime_module/config/Runtime.config.ts → contracts/Workflow.config.ts}

@@ -1,12 +1,15 @@
-import { defineConfig } from "../../../kernel";
+import { defineConfig } from "../../kernel";
 
 /**
- * Settings of the workflow background services (WORKFLOW-001 §4), from the
- * application configuration: `BAZIS_WORKFLOW__WORKER__ENABLED=false` keeps an
- * instance from running jobs, for example a web-only one.
+ * Settings of the workflow pack, from the application configuration:
+ * `BAZIS_WORKFLOW__WORKER__ENABLED=false` keeps an instance from running jobs,
+ * for example a web-only one (WORKFLOW-001 §4). `language` is the default
+ * language of texts, `languages` the comma-separated list a request may ask for
+ * with `Accept-Language` (WORKFLOW-002 §6).
  */
-/** The settings of the workflow background services, `workflow.*` in the configuration. */
 export interface WorkflowSettings {
+  readonly language: string;
+  readonly languages: string;
   readonly "worker.enabled": boolean;
   readonly "worker.intervalMs": number;
   readonly "worker.batchSize": number;
@@ -15,8 +18,12 @@ export interface WorkflowSettings {
   readonly "retention.batchSize": number;
 }
 
-export const workflowRuntimeConfig = defineConfig<WorkflowSettings>("workflow", {
+const LANGUAGE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+export const workflowConfig = defineConfig<WorkflowSettings>("workflow", {
   default: {
+    language: "en",
+    languages: "en",
     "worker.enabled": true,
     "worker.intervalMs": 1000,
     "worker.batchSize": 10,
@@ -25,6 +32,8 @@ export const workflowRuntimeConfig = defineConfig<WorkflowSettings>("workflow",
     "retention.batchSize": 500,
   },
   validate: {
+    language: (value) => (LANGUAGE.test(value) ? undefined : "must be a language: en, ru, pt-BR"),
+    languages: (value) => (value.split(",").every((item) => LANGUAGE.test(item.trim())) ? undefined : "must be a comma-separated list of languages"),
     "worker.intervalMs": (value) => positive(value, 3_600_000),
     "worker.batchSize": (value) => positive(value, 1000),
     "retention.intervalMs": (value) => positive(value, 86_400_000),

package/core/workflow/contracts/WorkflowExtensions.ts

@@ -0,0 +1,40 @@
+import type { WorkflowActor } from "./types";
+
+/** What every port of the pack learns about the call (WORKFLOW-002 §6). */
+export interface WorkflowPortContext {
+  readonly partition: string | null;
+  /** The language of the request; `workflow.language` for events, schedules and the background. */
+  readonly language: string;
+  /** `null` for a call from code. */
+  readonly actor: WorkflowActor | null;
+}
+
+/** Where the `extensions` are: a node, a variable, or neither for the root of the document. */
+export interface ExtensionTarget {
+  readonly node?: string;
+  readonly variable?: string;
+}
+
+/**
+ * Checks the application's data in a document (WORKFLOW-002 §3.1) when a draft
+ * is saved and a version is published: the application lists its namespaces and
+ * registers its implementation in any module. A namespace nobody checks is an
+ * error. A published version with such a key still runs: the engine does not
+ * read `extensions`, so a removed module does not break live processes.
+ */
+export abstract class WorkflowExtensions {
+  abstract namespaces(): readonly string[];
+  /** Every problem of `value`, the data of one namespace at one place. */
+  abstract check(namespace: string, value: unknown, target: ExtensionTarget, context: WorkflowPortContext): readonly string[] | Promise<readonly string[]>;
+}
+
+/** By default there are no namespaces. */
+export class DefaultWorkflowExtensions extends WorkflowExtensions {
+  namespaces(): readonly string[] {
+    return [];
+  }
+
+  check(): readonly string[] {
+    return [];
+  }
+}

package/core/workflow/contracts/WorkflowInputValidator.ts

@@ -1,16 +1,17 @@
 import { validateForm, type FormIssue, type FormSpec } from "../../../library/workflow";
+import type { WorkflowPortContext } from "./WorkflowExtensions";
 
 /** What a value is checked for: a process input or a task form. */
-export interface WorkflowInputContext {
+export interface WorkflowInputContext extends WorkflowPortContext {
   readonly purpose: "input" | "task";
   readonly processKey: string;
-  readonly partition: string | null;
 }
 
 /**
- * Checks a process input and task forms against their fields (WORKFLOW-001 §9).
- * The default checks the types of `bazis.workflow/v1`; an application with its
- * own field rules registers its implementation of this class in any module.
+ * Checks a process input and task forms against their fields (WORKFLOW-002 §3.4):
+ * a field carries the application's rules in `extensions`. The default checks the
+ * types; an application with its own field rules registers its implementation of
+ * this class in any module.
  */
 export abstract class WorkflowInputValidator {
   abstract validate(spec: FormSpec | undefined, value: unknown, context: WorkflowInputContext): { readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] } | Promise<{ readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] }>;

package/core/workflow/definitions_module/WorkflowDefinitions.module.ts

@@ -1,10 +1,16 @@
 import { AccessModule } from "../../access";
 import { HOSTED_SERVICE, Module, scoped, singleton } from "../../di";
 import { SystemWorkflowClock, WorkflowClock } from "../contracts/WorkflowClock";
+import { workflowConfig } from "../contracts/Workflow.config";
+import { DefaultWorkflowExtensions, WorkflowExtensions } from "../contracts/WorkflowExtensions";
 import { WorkflowEvents } from "../internal/WorkflowEvents";
+import { WorkflowLanguages } from "../internal/WorkflowLanguages";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { definitionsPermissions } from "./access/Definitions.permissions";
+import { FolderReferences } from "./access/Folder.references";
 import { ProcessReferences } from "./access/Process.references";
+import { ProcessFolderLookup } from "./access/ProcessFolder.lookup";
+import { CatalogImport } from "./code/CatalogImport";
 import { CodeProcessCatalog } from "./code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "./code/CodeProcessPublisher";
 import { ProcessesController } from "./http/Processes.controller";
@@ -16,23 +22,30 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
 
 /**
  * The process catalog: drafts and published versions, and the processes
- * declared in code ([passport](MODULE.md)).
+ * declared in code ([passport](MODULE.md)). The application checks its own
+ * `extensions` by registering its `WorkflowExtensions`.
  */
 @Module({
   imports: [AccessModule],
   permissions: definitionsPermissions,
-  references: { "workflow.process": ProcessReferences },
+  references: { "workflow.process": ProcessReferences, "workflow.folder": FolderReferences },
+  config: [workflowConfig],
   ormBazis: { context: DefinitionsDbContext, entities: [WfProcess, WfVersion], ownedStore: definitionsStore, registerRepositories: false },
   providers: [
     singleton(WorkflowClock, SystemWorkflowClock),
     singleton(WorkflowTools),
     singleton(CodeProcessCatalog),
+    singleton(WorkflowLanguages),
+    singleton(WorkflowExtensions, DefaultWorkflowExtensions),
     scoped(WorkflowEvents),
+    scoped(CatalogImport),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
     scoped(ProcessReferences),
+    scoped(FolderReferences),
+    scoped(ProcessFolderLookup),
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],
-  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents],
+  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, ProcessFolderLookup],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/access/Definitions.permissions.ts

@@ -1,6 +1,7 @@
 import { definePermissions } from "../../../access";
 
 const process = { ref: "workflow.process", column: "key" };
+const folder = { ref: "workflow.folder", column: "folder" };
 
 /**
  * The rights of the process catalog (WORKFLOW-002 §6.2). A process is one per
@@ -10,14 +11,14 @@ const process = { ref: "workflow.process", column: "key" };
 export const definitionsPermissions = definePermissions({
   "workflow.processes.read": {
     title: { en: "See processes", ru: "Видеть процессы" },
-    on: { process },
+    on: { process, folder },
   },
   "workflow.processes.manage": {
     title: { en: "Edit processes", ru: "Редактировать процессы" },
-    on: { process },
+    on: { process, folder },
   },
   "workflow.processes.publish": {
     title: { en: "Publish processes", ru: "Публиковать процессы" },
-    on: { process },
+    on: { process, folder },
   },
 });

package/core/workflow/definitions_module/access/Folder.references.ts

@@ -0,0 +1,37 @@
+import { References, type ReferenceItem, type ReferencePage } from "../../../access";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+
+/**
+ * Reference kind `workflow.folder`: the folders of the catalog. A folder exists
+ * while a process lies in it or below it: there is no folder entity.
+ */
+export class FolderReferences extends References {
+  constructor(private readonly db: DefinitionsDbContext) {
+    super();
+  }
+
+  async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
+    const folders = await this.folders();
+    return new Set(ids.filter((id) => folders.has(id)));
+  }
+
+  async describe(ids: readonly string[]): Promise<readonly ReferenceItem[]> {
+    const folders = await this.folders();
+    return ids.filter((id) => folders.has(id)).map((id) => ({ id, title: id }));
+  }
+
+  async search(text: string, _context: unknown, page: ReferencePage): Promise<readonly ReferenceItem[]> {
+    const found = text.trim().toLowerCase();
+    return [...await this.folders()].filter((folder) => folder.toLowerCase().includes(found)).sort().slice(page.offset, page.offset + page.limit).map((id) => ({ id, title: id }));
+  }
+
+  private async folders(): Promise<ReadonlySet<string>> {
+    const rows = await this.db.processes.asNoTracking().where((p) => p.folder.isNotNull()).select((p) => ({ folder: p.folder })).toList();
+    const all = new Set<string>();
+    for (const { folder } of rows) {
+      const parts = folder!.split("/");
+      for (let length = 1; length <= parts.length; length += 1) all.add(parts.slice(0, length).join("/"));
+    }
+    return all;
+  }
+}

package/core/workflow/definitions_module/access/Process.references.ts

@@ -20,7 +20,7 @@ export class ProcessReferences extends References {
   async search(text: string, _context: unknown, page: ReferencePage): Promise<readonly ReferenceItem[]> {
     const found = text.trim();
     let source = this.db.processes.asNoTracking();
-    if (found !== "") source = source.where((p) => p.key.contains(found, { ignoreCase: true }).or(p.title.contains(found, { ignoreCase: true })));
+    if (found !== "") source = source.where((p) => p.key.contains(found, { ignoreCase: true }).or(p.titleText.contains(found, { ignoreCase: true })));
     const rows = await source.orderBy((p) => p.key).skip(page.offset).take(page.limit).toList();
     return rows.map((row) => ({ id: row.key, title: row.title }));
   }

package/core/workflow/definitions_module/access/ProcessFolder.lookup.ts

@@ -0,0 +1,20 @@
+import { AttributeLookup, type AccessValue, type LookupColumn } from "../../../access";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+
+/** `folder` of rows that only know their process: folder → the keys of its processes (WORKFLOW-002 §6.2). */
+export class ProcessFolderLookup extends AttributeLookup {
+  constructor(private readonly db: DefinitionsDbContext) {
+    super();
+  }
+
+  async toColumn(values: readonly AccessValue[]): Promise<LookupColumn> {
+    const folders = values.filter((value): value is string => typeof value === "string");
+    const withoutFolder = values.includes(null);
+    if (folders.length === 0 && !withoutFolder) return { column: "processKey", in: [] };
+    const rows = await this.db.processes.asNoTracking()
+      .where((p) => (folders.length === 0 ? p.folder.isNull() : withoutFolder ? p.folder.isNull().or(p.folder.in(folders)) : p.folder.in(folders)))
+      .select((p) => ({ key: p.key }))
+      .toList();
+    return { column: "processKey", in: rows.map((row) => row.key) };
+  }
+}

package/core/workflow/definitions_module/code/CatalogImport.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { upgradeDocument, type LocalizedText } from "../../../../library/workflow";
+import { canonicalJson } from "../../internal/canonicalJson";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+import { WfProcess } from "../model/WfProcess.model";
+import { WfVersion } from "../model/WfVersion.model";
+
+
+/**
+ * Brings the catalog of the store before WORKFLOW-002 into the new one, once, at
+ * start (§9): processes and versions, documents through `upgradeDocument`,
+ * a title into the default language. Nothing happens without the old tables or
+ * when the new catalog has processes. Instances are not brought over. The old
+ * tables stay until they are dropped by hand (`upgrading.md`). Goes away with
+ * reading of version 1.
+ */
+export class CatalogImport {
+  constructor(
+    private readonly db: DefinitionsDbContext,
+    private readonly languages: WorkflowLanguages,
+  ) {}
+
+  /** How many processes came over. */
+  async run(): Promise<number> {
+    return await this.db.transactionScope(async () => {
+      // One importer at a time across application instances.
+      await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext('bazis.workflow.import'))");
+      const [{ old } = { old: null }] = await this.db.database.querySqlRaw("SELECT to_regclass('public.bazis_wf_def_processes')::text AS old");
+      if (old === null || await this.db.processes.asNoTracking().count() > 0) return 0;
+      const processes = await this.db.database.querySqlRaw('SELECT * FROM "bazis_wf_def_processes"');
+      const versions = await this.db.database.querySqlRaw('SELECT * FROM "bazis_wf_def_versions"');
+      const stamps: { readonly table: string; readonly column: string; readonly id: string; readonly at: Date }[] = [];
+      for (const row of processes) {
+        const title = text(row.title);
+        const process = Object.assign(new WfProcess(), {
+          id: String(row.id),
+          key: text(row.key),
+          title: { [this.languages.default]: title } satisfies LocalizedText,
+          titleText: title,
+          description: row.description === null ? null : { [this.languages.default]: text(row.description) } satisfies LocalizedText,
+          draft: upgradeDocument(json(row.draft)),
+          draftUpdatedAt: date(row.draftUpdatedAt),
+          draftUpdatedByKind: row.draftUpdatedByKind as string | null,
+          draftUpdatedById: row.draftUpdatedById as string | null,
+          latestVersion: row.latestVersion as number | null,
+          retentionDays: row.retentionDays as number | null,
+          archivedAt: date(row.archivedAt),
+        });
+        this.db.processes.add(process);
+        stamps.push({ table: "bazis_wf2_def_processes", column: "createdAt", id: process.id, at: date(row.createdAt)! });
+      }
+      await this.db.saveChanges();
+      for (const row of versions) {
+        const document = upgradeDocument(json(row.document));
+        const version = Object.assign(new WfVersion(), {
+          id: String(row.id),
+          processId: String(row.processId),
+          version: row.version as number,
+          document,
+          documentHash: createHash("sha256").update(canonicalJson(document)).digest("hex"),
+          publishedByKind: text(row.publishedByKind),
+          publishedById: text(row.publishedById),
+        });
+        this.db.versions.add(version);
+        stamps.push({ table: "bazis_wf2_def_versions", column: "publishedAt", id: version.id, at: date(row.publishedAt)! });
+      }
+      await this.db.saveChanges();
+      // These columns fill themselves on insert: the history keeps its dates.
+      for (const { table, column, id, at } of stamps) {
+        await this.db.database.executeSqlRaw(`UPDATE "${table}" SET "${column}" = {0} WHERE "id" = {1}::uuid`, at, id);
+      }
+      return processes.length;
+    });
+  }
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : String(value ?? "");
+}
+
+function date(value: unknown): Date | null {
+  return value === null || value === undefined ? null : new Date(value as string | Date);
+}
+
+/** A raw `json` column may come parsed or as text, depending on the driver. */
+function json(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+

package/core/workflow/definitions_module/code/CodeProcessPublisher.ts

@@ -3,14 +3,16 @@ import type { HostedService } from "../../../di/extensions/hosted-service";
 import { LOGGER } from "../../../kernel";
 import { WorkflowTools } from "../../internal/WorkflowTools";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
+import { CatalogImport } from "./CatalogImport";
 import { CodeProcessCatalog } from "./CodeProcessCatalog";
 import { definitionProblems, WorkflowSetupError } from "./codeProcesses";
 
 /**
- * Publishes the processes of `@Module({ processes })` at start, after the
- * tables exist (WORKFLOW-001 §14). A document with an unknown Tool stops the
- * start with every finding of every process; the same document again gives no
- * new version.
+ * At start, after the tables exist: brings over the catalog of the old store
+ * (WORKFLOW-002 §9), then publishes the processes of `@Module({ processes })`
+ * (WORKFLOW-001 §14). A document with an unknown Tool or an `extensions` namespace
+ * nobody checks stops the start with every finding of every process; the same
+ * document again gives no new version.
  */
 export class CodeProcessPublisher implements HostedService {
   readonly diagnosticName = "workflow:processes";
@@ -18,20 +20,28 @@ export class CodeProcessPublisher implements HostedService {
   constructor(private readonly services: ServiceProvider) {}
 
   async start(): Promise<void> {
-    const entries = this.services.resolve(CodeProcessCatalog).list();
-    if (entries.length === 0) return;
-    const tools = this.services.resolve(WorkflowTools);
-    const problems = entries.flatMap(({ process, module }) => {
-      const found = definitionProblems(process, (name) => tools.has(name));
-      return found.length === 0 ? [] : [`${module}: process "${process.key}":\n${found.map((line) => `  - ${line}`).join("\n")}`];
-    });
-    if (problems.length > 0) {
-      throw markConfigurationError(new WorkflowSetupError(`Processes declared in code cannot be published:\n${problems.join("\n")}`));
-    }
+    const logger = this.services.tryResolve(LOGGER);
     const scope = this.services.createScope();
     try {
-      const results = await scope.resolve(IWorkflowDefinitions).publishCode(entries);
-      this.services.tryResolve(LOGGER)?.info("workflow processes from code", {
+      const imported = await scope.resolve(CatalogImport).run();
+      if (imported > 0) logger?.info("workflow catalog brought over from the old store", { processes: imported });
+      const entries = this.services.resolve(CodeProcessCatalog).list();
+      if (entries.length === 0) return;
+      const tools = this.services.resolve(WorkflowTools);
+      const definitions = scope.resolve(IWorkflowDefinitions);
+      const problems: string[] = [];
+      for (const { process, module } of entries) {
+        const found = [...definitionProblems(process, (name) => tools.has(name))];
+        for (const issue of await definitions.validate(process.document)) {
+          if (issue.severity === "error" && (issue.code === "extension_unknown" || issue.code === "extension_invalid")) found.push(`${issue.message} (${issue.code})`);
+        }
+        if (found.length > 0) problems.push(`${module}: process "${process.key}":\n${found.map((line) => `  - ${line}`).join("\n")}`);
+      }
+      if (problems.length > 0) {
+        throw markConfigurationError(new WorkflowSetupError(`Processes declared in code cannot be published:\n${problems.join("\n")}`));
+      }
+      const results = await definitions.publishCode(entries);
+      logger?.info("workflow processes from code", {
         published: results.filter((result) => result.published).map((result) => `${result.key} v${result.version}`),
         unchanged: results.filter((result) => !result.published).map((result) => result.key),
       });

package/core/workflow/definitions_module/code/codeProcesses.ts

@@ -6,7 +6,7 @@ import {
   type BazisModuleMetadata,
   type ServiceProvider,
 } from "../../../di";
-import { validateProcess, type ProcessIssue } from "../../../../library/workflow";
+import { checkLocalizedText, validateProcess, type ProcessIssue } from "../../../../library/workflow";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 import { isCodeProcess, type CodeProcess } from "./defineProcess";
 
@@ -66,8 +66,12 @@ export function codeProcessesOf(services: ServiceProvider): readonly OwnedCodePr
 export function definitionProblems(process: CodeProcess, tools?: (name: string) => boolean): readonly string[] {
   const problems: string[] = [];
   if (typeof process.key !== "string" || !KEY.test(process.key)) problems.push("key must match ^[a-z][a-z0-9_.-]{0,63}$");
-  if (typeof process.title !== "string" || process.title.trim() === "" || process.title.length > 200) problems.push("title must be 1–200 characters");
-  if (process.description != null && (typeof process.description !== "string" || process.description.length > 2000)) problems.push("description must be up to 2000 characters");
+  const title = checkLocalizedText(process.title, 200);
+  if (title) problems.push(`title ${title}`);
+  const description = process.description == null ? null : checkLocalizedText(process.description, 2000, 0);
+  if (description) problems.push(`description ${description}`);
+  if (process.folder != null && (typeof process.folder !== "string" || !/^[^/\s](?:[^/]*[^/\s])?(?:\/[^/\s](?:[^/]*[^/\s])?)*$/.test(process.folder))) problems.push("folder must be a path like Sales/Orders");
+  if (process.owner != null && (typeof process.owner !== "string" || process.owner === "" || process.owner.length > 200)) problems.push("owner must be up to 200 characters");
   if (process.retentionDays != null && (!Number.isSafeInteger(process.retentionDays) || process.retentionDays < 1 || process.retentionDays > 36_500)) problems.push("retentionDays must be an integer 1–36500");
   problems.push(...documentErrors(validateProcess(process.document, tools === undefined ? {} : { tools })));
   return problems;

package/core/workflow/definitions_module/code/defineProcess.ts

@@ -1,4 +1,4 @@
-import type { ProcessDocument } from "../../../../library/workflow";
+import type { LocalizedText, ProcessDocument } from "../../../../library/workflow";
 
 const CODE_PROCESS = Symbol.for("bazis/core/workflow/code-process");
 
@@ -6,8 +6,12 @@ const CODE_PROCESS = Symbol.for("bazis/core/workflow/code-process");
 export interface ProcessDefinition {
   /** The key it is started by: `^[a-z][a-z0-9_.-]{0,63}$`. */
   readonly key: string;
-  readonly title: string;
-  readonly description?: string | null;
+  readonly title: LocalizedText;
+  readonly description?: LocalizedText | null;
+  /** A path in the catalog: `Sales/Orders`. */
+  readonly folder?: string | null;
+  /** Whose process it is: an opaque id. */
+  readonly owner?: string | null;
   /** Days to keep completed and cancelled instances; omitted keeps them. */
   readonly retentionDays?: number | null;
   readonly document: ProcessDocument;
@@ -27,9 +31,11 @@ export interface CodeProcess extends ProcessDefinition {
  * export const OrderApprovalProcess = defineProcess({
  *   key: "order-approval",
  *   title: "Order approval",
- *   document: { schemaVersion: "bazis.workflow/v1", nodes: { … }, flows: { … } },
+ *   document: { schemaVersion: "bazis.workflow/v2", nodes: { … }, flows: { … } },
  * });
  * ```
+ *
+ * A document of version 1 goes through `upgradeDocument`.
  */
 export function defineProcess(definition: ProcessDefinition): CodeProcess {
   return Object.freeze({ ...definition, [CODE_PROCESS]: true as const });