bazis 0.130.0 → 0.132.0

package/core/workflow/definitions_module/services/WorkflowDefinitions.service.ts

@@ -1,14 +1,20 @@
 import { grantsToWhere } from "../../../access";
 import { createHash } from "node:crypto";
-import { UniqueViolationError } from "../../../orm";
+import { paginate, UniqueViolationError } from "../../../orm";
 import type { AgentToolContract } from "../../../agent";
-import { emptyProcess, hasErrors, validateProcess, type ProcessDocument, type ProcessIssue } from "../../../../library/workflow";
-import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
+import { allTexts, checkLocalizedText, emptyProcess, hasErrors, processPalette, validateProcess, type LocalizedText, type ProcessDocument, type ProcessIssue, type ProcessPalette } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
+import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowAuditOptions, type WorkflowPage } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import { WorkflowError } from "../../contracts/WorkflowError";
+import { WorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "../../contracts/WorkflowExtensions";
+import { canonicalJson } from "../../internal/canonicalJson";
+import type { WorkflowEvents } from "../../internal/WorkflowEvents";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { CodeProcessCatalog } from "../code/CodeProcessCatalog";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
+import { WORKFLOW_PROCESS_CHANGED, type ProcessChange } from "../events/Definitions.events";
 import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
 import { WfProcess } from "../model/WfProcess.model";
 import { WfVersion } from "../model/WfVersion.model";
@@ -18,12 +24,17 @@ import {
   type ProcessDetails,
   type ProcessListQuery,
   type ProcessSummary,
+  type SavedDraft,
+  type SaveDraftOptions,
   type UpdateProcess,
+  type ValidateOptions,
   type VersionDetails,
   type VersionSummary,
 } from "./IWorkflowDefinitions.service";
 
 const KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+/** A path of segments without empty ones: `Sales/Orders`. */
+const FOLDER = /^[^/\s](?:[^/]*[^/\s])?(?:\/[^/\s](?:[^/]*[^/\s])?)*$/;
 /** Who publishes the processes declared in code. */
 const CODE_ACTOR: WorkflowActor = { kind: "system", id: "code" };
 
@@ -33,12 +44,15 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     private readonly workflowTools: WorkflowTools,
     private readonly code: CodeProcessCatalog,
     private readonly clock: WorkflowClock,
+    private readonly events: WorkflowEvents,
+    private readonly languages: WorkflowLanguages,
+    /** The scope: the port is asked here, so that the application's own registration replaces the default. */
+    private readonly services: ServiceProvider,
   ) {
     super();
   }
 
   async list(query: ProcessListQuery = {}): Promise<WorkflowPage<ProcessSummary>> {
-    const { limit, offset } = pagingOf(query);
     const where = query.access === undefined ? "all" : grantsToWhere(query.access);
     if (where === "none") return { items: [], total: 0 };
     let source = this.db.processes.asNoTracking();
@@ -47,23 +61,61 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     if (query.archived === false) source = source.where((p) => p.archivedAt.isNull());
     if (query.search !== undefined && query.search.trim() !== "") {
       const text = query.search.trim();
-      source = source.where((p) => p.key.contains(text, { ignoreCase: true }).or(p.title.contains(text, { ignoreCase: true })));
+      source = source.where((p) => p.key.contains(text, { ignoreCase: true }).or(p.titleText.contains(text, { ignoreCase: true })));
     }
-    const total = await source.count();
-    const rows = await source.orderBy((p) => p.key).skip(offset).take(limit).toList();
-    return { items: rows.map((row) => this.summaryOf(row)), total };
+    if (query.folder !== undefined) {
+      const folder = query.folder;
+      source = source.where((p) => p.folder.eq(folder).or(p.folder.startsWith(`${folder}/`)));
+    }
+    if (query.owner !== undefined) source = source.where((p) => p.owner.eq(query.owner!));
+    // The list sorts by a title as `titleText`: `title` itself is JSON.
+    const sort = query.sort?.map((field) => (field.field === "title" ? { ...field, field: "titleText" } : field));
+    const { items, total } = await paginate(source, pageQueryOf({ ...query, ...(sort === undefined ? {} : { sort }) }, { field: "key", dir: "asc" }));
+    return { items: items.map((row) => this.summaryOf(row)), total };
   }
 
   async get(key: string): Promise<ProcessDetails> {
     return this.detailsOf(await this.process(key, false));
   }
 
-  async create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails> {
+  async folderOf(key: string): Promise<string | null> {
+    const row = await this.db.processes.asNoTracking().firstOrDefault((p) => p.key.eq(key));
+    return row?.folder ?? null;
+  }
+
+  async validate(document: unknown, options: ValidateOptions = {}): Promise<readonly ProcessIssue[]> {
+    const port = this.services.resolve(WorkflowExtensions);
+    const namespaces = new Set(port.namespaces());
+    const issues = validateProcess(document, { tools: (name) => this.workflowTools.has(name), extensions: (namespace) => namespaces.has(namespace) });
+    if (namespaces.size === 0 || issues.some((issue) => issue.code === "too_large" || issue.code === "schema")) return issues;
+    const context: WorkflowPortContext = { partition: null, language: options.language ?? this.languages.default, actor: options.actor ?? null };
+    const found: ProcessIssue[] = [...issues];
+    const { extensions, variables, nodes } = document as ProcessDocument;
+    const checkAll = async (data: Readonly<Record<string, unknown>> | undefined, target: ExtensionTarget): Promise<void> => {
+      if (typeof data !== "object" || data === null) return;
+      for (const [namespace, value] of Object.entries(data)) {
+        if (!namespaces.has(namespace)) continue;
+        for (const message of await port.check(namespace, value, target, context)) found.push({ severity: "error", code: "extension_invalid", message: `${namespace}: ${message}`, ...target });
+      }
+    };
+    await checkAll(extensions, {});
+    if (Array.isArray(variables)) for (const variable of variables) await checkAll(variable?.extensions, { variable: variable?.name });
+    for (const [node, raw] of Object.entries(nodes)) await checkAll(raw?.extensions, { node });
+    return found;
+  }
+
+  palette(): ProcessPalette {
+    return processPalette(this.tools());
+  }
+
+  async create(process: CreateProcess, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<ProcessDetails> {
     if (typeof process.key !== "string" || !KEY.test(process.key)) throw new WorkflowError("invalid_input", "key must match ^[a-z][a-z0-9_.-]{0,63}$");
     const row = Object.assign(new WfProcess(), {
       key: process.key,
-      title: title(process.title),
+      ...this.titled(process.title),
       description: description(process.description),
+      folder: folder(process.folder),
+      owner: owner(process.owner),
       retentionDays: retention(process.retentionDays),
       draft: emptyProcess(),
       draftUpdatedAt: this.clock.now(),
@@ -77,43 +129,60 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       if (error instanceof UniqueViolationError) throw new WorkflowError("conflict", `Process ${process.key} already exists`);
       throw error;
     }
+    await this.changed("created", row.key, actor, options);
     return this.detailsOf(row);
   }
 
-  async update(key: string, changes: UpdateProcess, _actor: WorkflowActor): Promise<ProcessDetails> {
+  async update(key: string, changes: UpdateProcess, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<ProcessDetails> {
     const row = await this.process(key, true);
     const { archived, ...fields } = changes;
     if (Object.values(fields).some((value) => value !== undefined)) this.assertNotCode(key);
-    if (changes.title !== undefined) row.title = title(changes.title);
+    const card = (): string => canonicalJson({ title: row.title, description: row.description, folder: row.folder, owner: row.owner, retentionDays: row.retentionDays });
+    const before = { card: card(), archived: row.archivedAt !== null };
+    if (changes.title !== undefined) Object.assign(row, this.titled(changes.title));
     if (changes.description !== undefined) row.description = description(changes.description);
+    if (changes.folder !== undefined) row.folder = folder(changes.folder);
+    if (changes.owner !== undefined) row.owner = owner(changes.owner);
     if (changes.retentionDays !== undefined) row.retentionDays = retention(changes.retentionDays);
     if (archived !== undefined) row.archivedAt = archived ? row.archivedAt ?? this.clock.now() : null;
     await this.db.saveChanges();
+    if (card() !== before.card) await this.changed("updated", key, actor, options);
+    if (archived !== undefined && archived !== before.archived) await this.changed(archived ? "archived" : "restored", key, actor, options);
     return this.detailsOf(row);
   }
 
-  async saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }> {
-    const issues = this.validate(document);
+  async saveDraft(key: string, document: unknown, actor: WorkflowActor, options: SaveDraftOptions = {}): Promise<SavedDraft> {
+    const issues = await this.validate(document, { actor, ...(options.language === undefined ? {} : { language: options.language }) });
     if (issues.some((issue) => issue.code === "too_large")) throw new WorkflowError("invalid_document", "The document is too large", issues);
-    const row = await this.process(key, true);
-    this.assertNotCode(key);
-    row.draft = document;
-    row.draftUpdatedAt = this.clock.now();
-    row.draftUpdatedByKind = actor.kind;
-    row.draftUpdatedById = actor.id;
-    await this.db.saveChanges();
-    return { issues };
+    return await this.db.transactionScope(async (transaction) => {
+      const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
+      if (!row) throw notFound(key);
+      this.assertNotCode(key);
+      const previous = row.draftUpdatedAt?.getTime();
+      if (options.expected !== undefined && previous !== options.expected.getTime()) throw new WorkflowError("conflict", `The draft of ${key} was saved by someone else`);
+      // Later than the last save even within a millisecond: `expected` tells any two saves apart.
+      const draftUpdatedAt = new Date(Math.max(this.clock.now().getTime(), (previous ?? 0) + 1));
+      row.draft = document;
+      row.draftUpdatedAt = draftUpdatedAt;
+      row.draftUpdatedByKind = actor.kind;
+      row.draftUpdatedById = actor.id;
+      await this.db.saveChanges();
+      transaction.afterCommit(() => this.changed("draftSaved", key, actor, options));
+      return { issues, draftUpdatedAt };
+    });
   }
 
-  async publish(key: string, actor: WorkflowActor): Promise<VersionDetails> {
-    return await this.db.transactionScope(async () => {
+  async publish(key: string, actor: WorkflowActor, options: WorkflowAuditOptions & Pick<ValidateOptions, "language"> = {}): Promise<VersionDetails> {
+    return await this.db.transactionScope(async (transaction) => {
       const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
       if (!row) throw notFound(key);
       this.assertNotCode(key);
       if (row.archivedAt !== null) throw new WorkflowError("archived", `Process ${key} is archived`);
-      const issues = this.validate(row.draft);
+      const issues = await this.validate(row.draft, { actor, ...(options.language === undefined ? {} : { language: options.language }) });
       if (hasErrors(issues)) throw new WorkflowError("invalid_document", `Process ${key} has errors and cannot be published`, issues);
-      return (await this.publishDraft(row, actor)).version;
+      const { version, created } = await this.publishDraft(row, actor);
+      if (created) transaction.afterCommit(() => this.changed("published", key, actor, options, version.version));
+      return version;
     });
   }
 
@@ -124,7 +193,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
    * and unpublished. The caller has checked the documents with the Tools.
    */
   async publishCode(entries: readonly OwnedCodeProcess[]): Promise<readonly { readonly key: string; readonly version: number | null; readonly published: boolean }[]> {
-    return await this.db.transactionScope(async () => {
+    return await this.db.transactionScope(async (transaction) => {
       await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext('bazis.workflow.code'))");
       const results: { key: string; version: number | null; published: boolean }[] = [];
       for (const { process } of [...entries].sort((a, b) => a.process.key.localeCompare(b.process.key))) {
@@ -132,10 +201,15 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
         if (!row) {
           row = Object.assign(new WfProcess(), { key: process.key });
           this.db.processes.add(row);
+          transaction.afterCommit(() => this.changed("created", process.key, CODE_ACTOR));
         }
-        const fields = { title: title(process.title), description: description(process.description), retentionDays: retention(process.retentionDays) };
-        if (row.title !== fields.title) row.title = fields.title;
-        if (row.description !== fields.description) row.description = fields.description;
+        const named = this.titled(process.title);
+        const about = description(process.description);
+        if (canonicalJson(row.title) !== canonicalJson(named.title)) Object.assign(row, named);
+        if (canonicalJson(row.description) !== canonicalJson(about)) row.description = about;
+        const fields = { folder: folder(process.folder), owner: owner(process.owner), retentionDays: retention(process.retentionDays) };
+        if (row.folder !== fields.folder) row.folder = fields.folder;
+        if (row.owner !== fields.owner) row.owner = fields.owner;
         if (row.retentionDays !== fields.retentionDays) row.retentionDays = fields.retentionDays;
         if (row.draft === null || canonicalJson(row.draft) !== canonicalJson(process.document)) {
           row.draft = process.document;
@@ -149,6 +223,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
           continue;
         }
         const { version, created } = await this.publishDraft(row, CODE_ACTOR);
+        if (created) transaction.afterCommit(() => this.changed("published", process.key, CODE_ACTOR, {}, version.version));
         results.push({ key: row.key, version: version.version, published: created });
       }
       return results;
@@ -226,6 +301,10 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return this.workflowTools.list();
   }
 
+  private async changed(change: ProcessChange, key: string, actor: WorkflowActor, options: WorkflowAuditOptions = {}, version: number | null = null): Promise<void> {
+    await this.events.publish(WORKFLOW_PROCESS_CHANGED, { change, key, version, actor, request: options.request ?? null });
+  }
+
   /** A process declared in code changes only through the code. */
   private assertNotCode(key: string): void {
     const module = this.code.moduleOf(key);
@@ -237,6 +316,8 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       key: row.key,
       title: row.title,
       description: row.description,
+      folder: row.folder,
+      owner: row.owner,
       latestVersion: row.latestVersion,
       retentionDays: row.retentionDays,
       archived: row.archivedAt !== null,
@@ -255,8 +336,11 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     };
   }
 
-  private validate(document: unknown): ProcessIssue[] {
-    return validateProcess(document, { tools: (name) => this.workflowTools.has(name) });
+  /** A title with the column a list searches and sorts by. */
+  private titled(value: unknown): { readonly title: LocalizedText; readonly titleText: string } {
+    const problem = checkLocalizedText(value, 200);
+    if (problem) throw new WorkflowError("invalid_input", `title ${problem}`);
+    return { title: value as LocalizedText, titleText: allTexts(value as LocalizedText, this.languages.default) };
   }
 
   private async process(key: string, tracked: boolean): Promise<WfProcess> {
@@ -271,14 +355,22 @@ function notFound(key: string): WorkflowError {
   return new WorkflowError("not_found", `Process ${key} does not exist`);
 }
 
-function title(value: unknown): string {
-  if (typeof value !== "string" || value.trim() === "" || value.length > 200) throw new WorkflowError("invalid_input", "title must be 1–200 characters");
+function description(value: unknown): LocalizedText | null {
+  if (value === undefined || value === null) return null;
+  const problem = checkLocalizedText(value, 2000, 0);
+  if (problem) throw new WorkflowError("invalid_input", `description ${problem}`);
+  return value as LocalizedText;
+}
+
+function folder(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || value.length > 500 || !FOLDER.test(value)) throw new WorkflowError("invalid_input", "folder must be a path like Sales/Orders");
   return value;
 }
 
-function description(value: unknown): string | null {
+function owner(value: unknown): string | null {
   if (value === undefined || value === null) return null;
-  if (typeof value !== "string" || value.length > 2000) throw new WorkflowError("invalid_input", "description must be up to 2000 characters");
+  if (typeof value !== "string" || value === "" || value.length > 200) throw new WorkflowError("invalid_input", "owner must be up to 200 characters");
   return value;
 }
 
@@ -298,12 +390,3 @@ function versionOf(key: string, row: WfVersion): VersionDetails {
     document: row.document as ProcessDocument,
   };
 }
-
-/** JSON with sorted keys: the same document gives the same hash whatever the key order. */
-function canonicalJson(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (typeof value === "object" && value !== null) {
-    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
-}

package/core/workflow/generated/deps.ts

@@ -5,13 +5,18 @@ import { DbContextOptions } from "../../../library/orm/DbContextOptions";
 import { ServiceProvider } from "../../di/ServiceProvider";
 import { EventBus } from "../../kernel/events/EventBus";
 import { WorkflowClock } from "../contracts/WorkflowClock";
+import { FolderReferences } from "../definitions_module/access/Folder.references";
 import { ProcessReferences } from "../definitions_module/access/Process.references";
+import { ProcessFolderLookup } from "../definitions_module/access/ProcessFolder.lookup";
+import { CatalogImport } from "../definitions_module/code/CatalogImport";
 import { CodeProcessCatalog } from "../definitions_module/code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "../definitions_module/code/CodeProcessPublisher";
 import { ProcessesController } from "../definitions_module/http/Processes.controller";
 import { DefinitionsDbContext } from "../definitions_module/model/Definitions.dbContext";
 import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
 import { WorkflowDefinitions } from "../definitions_module/services/WorkflowDefinitions.service";
+import { WorkflowEvents } from "../internal/WorkflowEvents";
+import { WorkflowLanguages } from "../internal/WorkflowLanguages";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { WorkflowRetention } from "../runtime_module/background/WorkflowRetention";
 import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
@@ -32,12 +37,15 @@ import { IWorkflowTasks } from "../tasks_module/services/IWorkflowTasks.service"
 import { WorkflowTasks } from "../tasks_module/services/WorkflowTasks.service";
 
 registerFrameworkClassDeps([
+  [CatalogImport, [DefinitionsDbContext, WorkflowLanguages]],
   [CodeProcessCatalog, [ServiceProvider]],
   [CodeProcessPublisher, [ServiceProvider]],
   [DefinitionsDbContext, [DbContextOptions]],
   [EventsController, [IWorkflowRuntime]],
-  [InstancesController, [IWorkflowRuntime]],
+  [FolderReferences, [DefinitionsDbContext]],
+  [InstancesController, [IWorkflowRuntime, IWorkflowDefinitions]],
   [ProcessesController, [IWorkflowDefinitions]],
+  [ProcessFolderLookup, [DefinitionsDbContext]],
   [ProcessReferences, [DefinitionsDbContext]],
   [RuntimeDbContext, [DbContextOptions]],
   [Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions]],
@@ -46,11 +54,13 @@ registerFrameworkClassDeps([
   [TasksDbContext, [DbContextOptions]],
   [TimerStep, [RuntimeDbContext, WorkflowEngine]],
   [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools]],
-  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock]],
-  [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, EventBus, ServiceProvider, WorkflowClock, "optional:Logger"]],
+  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, ServiceProvider]],
+  [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
+  [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
+  [WorkflowLanguages, ["Config:workflow"]],
   [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
-  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider]],
-  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock]],
+  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider, WorkflowLanguages]],
+  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock, WorkflowEvents]],
   [WorkflowTools, [ServiceProvider]],
   [WorkflowWorker, [ServiceProvider, "Config:workflow"]],
 ]);

package/core/workflow/index.ts

@@ -1,5 +1,5 @@
 /**
- * Business processes without a UI (WORKFLOW-001): the composite `WorkflowModule`
+ * Business processes without a UI (WORKFLOW-001, WORKFLOW-002): the composite `WorkflowModule`
  * with the Definitions and Runtime parts, their services, HTTP, events and
  * extension points. The document format is `bazis/library/workflow`.
  */
@@ -14,6 +14,8 @@ export { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefiniti
 export { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
 export { WorkflowTasksModule } from "./tasks_module/WorkflowTasks.module";
 export { IWorkflowTasks, type TaskDetails, type TaskListQuery } from "./tasks_module/services/IWorkflowTasks.service";
+export { WORKFLOW_TASK_COMPLETED, type WorkflowTaskCompleted } from "./tasks_module/events/Tasks.events";
+export { WORKFLOW_PROCESS_CHANGED, type ProcessChange, type WorkflowProcessChanged } from "./definitions_module/events/Definitions.events";
 export type { TaskStatus } from "./tasks_module/model/WfTask.model";
 export {
   IWorkflowDefinitions,
@@ -21,38 +23,50 @@ export {
   type ProcessDetails,
   type ProcessListQuery,
   type ProcessSummary,
+  type SavedDraft,
+  type SaveDraftOptions,
   type UpdateProcess,
+  type ValidateOptions,
   type VersionDetails,
   type VersionSummary,
 } from "./definitions_module/services/IWorkflowDefinitions.service";
 export {
   IWorkflowRuntime,
+  type CancelInstance,
   type EmitOptions,
   type EmitResult,
   type HistoryEntry,
   type InstanceDetails,
   type InstanceListQuery,
   type InstanceSummary,
+  type RetryInstance,
   type StartInstance,
   type TokenDetails,
 } from "./runtime_module/services/IWorkflowRuntime.service";
 export {
+  WORKFLOW_INSTANCE_CANCELLED,
   WORKFLOW_INSTANCE_FINISHED,
+  WORKFLOW_INSTANCE_RETRIED,
+  WORKFLOW_INSTANCE_STARTED,
   WORKFLOW_INSTANCES_DELETED,
   WORKFLOW_TASK_REQUESTED,
   WORKFLOW_TOKEN_CLOSED,
+  type WorkflowInstanceCancelled,
   type WorkflowInstanceFinished,
+  type WorkflowInstanceRetried,
+  type WorkflowInstanceStarted,
   type WorkflowInstancesDeleted,
   type WorkflowTaskRequested,
   type WorkflowTokenClosed,
 } from "./runtime_module/events/Runtime.events";
-export { workflowRuntimeConfig } from "./runtime_module/config/Runtime.config";
+export { workflowConfig, type WorkflowSettings } from "./contracts/Workflow.config";
 export type { HistoryType } from "./runtime_module/model/WfHistory.model";
 export type { InstanceStatus, StartedVia } from "./runtime_module/model/WfInstance.model";
 export type { TokenStatus } from "./runtime_module/model/WfToken.model";
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
+export { WorkflowExtensions, DefaultWorkflowExtensions, type ExtensionTarget, type WorkflowPortContext } from "./contracts/WorkflowExtensions";
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
-export type { WorkflowActor, WorkflowPage, WorkflowPaging } from "./contracts/types";
+export type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging, WorkflowRequest, WorkflowToolMetadata } from "./contracts/types";
 
 // Augment the declaring file, not the "../di" re-export: re-export targets
 // depend on program file order and silently stop merging in some projects.

package/core/workflow/internal/WorkflowEvents.ts

@@ -0,0 +1,23 @@
+import type { ServiceProvider } from "../../di";
+import { EventBus, type EventToken, type Logger } from "../../kernel";
+
+/**
+ * Publishes the events of the workflow services after their action is saved, in
+ * the scope of the action. A failing handler is logged: the action stands.
+ */
+export class WorkflowEvents {
+  constructor(
+    private readonly bus: EventBus,
+    /** Event handlers run in this scope. */
+    private readonly scope: ServiceProvider,
+    private readonly logger?: Logger,
+  ) {}
+
+  async publish<T>(event: EventToken<T>, payload: T): Promise<void> {
+    try {
+      await this.bus.publishScoped(this.scope, event, payload);
+    } catch (error) {
+      this.logger?.error("workflow event handler failed", { event: event.name, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+}

package/core/workflow/internal/WorkflowLanguages.ts

@@ -0,0 +1,35 @@
+import type { ConfigView } from "../../kernel";
+import type { WorkflowSettings } from "../contracts/Workflow.config";
+
+/**
+ * The language of a call (WORKFLOW-002 §6): over HTTP from `Accept-Language`
+ * among `workflow.languages`, otherwise `workflow.language`; in events, schedules
+ * and the background always `workflow.language`.
+ */
+export class WorkflowLanguages {
+  constructor(private readonly config: ConfigView<WorkflowSettings>) {}
+
+  get default(): string {
+    return this.config.get("language");
+  }
+
+  /** The best language of an `Accept-Language` header: by weight, then by order; `ru-RU` also finds `ru`. */
+  of(header: string | undefined): string {
+    if (header === undefined) return this.default;
+    const known = new Set([this.default, ...this.config.get("languages").split(",").map((item) => item.trim())]);
+    const wanted = header.split(",")
+      .map((part, index) => {
+        const [tag = "", ...parameters] = part.trim().split(";");
+        const weight = parameters.map((item) => /^\s*q=([\d.]+)\s*$/.exec(item)?.[1]).find((item) => item !== undefined);
+        return { tag: tag.trim(), weight: weight === undefined ? 1 : Number(weight), index };
+      })
+      .filter(({ tag, weight }) => tag !== "" && weight > 0)
+      .sort((a, b) => b.weight - a.weight || a.index - b.index);
+    for (const { tag } of wanted) {
+      if (known.has(tag)) return tag;
+      const base = tag.split("-")[0]!;
+      if (known.has(base)) return base;
+    }
+    return this.default;
+  }
+}

package/core/workflow/internal/canonicalJson.ts

@@ -0,0 +1,8 @@
+/** JSON with sorted keys: the same document gives the same hash whatever the key order. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object" && value !== null) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}

package/core/workflow/internal/http.ts

@@ -1,12 +1,29 @@
 import { IAccess, type AccessObject, type SubjectAccess } from "../../access";
 import { ForbiddenError, type HttpContext } from "../../http";
-import type { WorkflowActor } from "../contracts/types";
+import { frameworkBadRequest } from "../../http/Errors/HttpError";
+import { ListQueryError, parseListQuery, type ListQuery, type ListQueryOptions, type ListQueryProblem } from "../../../library/jsonapi";
+import { textOf, type LocalizedText } from "../../../library/workflow";
+import type { WorkflowActor, WorkflowPaging, WorkflowRequest } from "../contracts/types";
 import { WorkflowError } from "../contracts/WorkflowError";
+import { WorkflowLanguages } from "./WorkflowLanguages";
 
 /** Who calls a route: their rights and how they are recorded as an actor. */
 export interface WorkflowCaller {
   readonly access: SubjectAccess;
   readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest;
+  /** The language of the request: `Accept-Language` among `workflow.languages`. */
+  readonly language: string;
+}
+
+/** A record with `titleText`: its `title` in the language of the request. `title` itself stays for editing. */
+export function withTitleText<T extends { readonly title: LocalizedText }>(item: T, language: string, fallback: string): T & { readonly titleText: string } {
+  return { ...item, titleText: textOf(item.title, language, fallback) };
+}
+
+/** The default language, for {@link withTitleText}. */
+export function defaultLanguage(ctx: HttpContext): string {
+  return ctx.services.resolve(WorkflowLanguages).default;
 }
 
 /**
@@ -20,7 +37,7 @@ export async function callerOf(ctx: HttpContext, permission?: string, object?: A
   if (permission !== undefined && !await access.can(permission, object)) throw new ForbiddenError();
   const sub = access.subject.sub;
   const [id = sub.slice(sub.lastIndexOf(":") + 1)] = await access.ownerIds();
-  return { access, actor: { kind: "user", id } };
+  return { access, actor: { kind: "user", id }, request: { ip: ctx.clientIp ?? null, userAgent: ctx.header("user-agent") ?? null }, language: ctx.services.resolve(WorkflowLanguages).of(ctx.header("accept-language")) };
 }
 
 /** A route parameter as a string. */
@@ -28,6 +45,11 @@ export function param(ctx: HttpContext, name: string): string {
   return String(ctx.params[name] ?? "");
 }
 
+/** A title or a description from a body; the service checks it. */
+export function optionalText(value: unknown): LocalizedText | null | undefined {
+  return value as LocalizedText | null | undefined;
+}
+
 /** The JSON body as an object; anything else is `invalid_input`. */
 export async function body(ctx: HttpContext): Promise<Record<string, unknown>> {
   const text = await ctx.text();
@@ -64,7 +86,33 @@ export function optionalInteger(value: unknown, name: string): number | undefine
   return number as number;
 }
 
-/** `limit` and `offset` of a list query. */
-export function pagingQuery(ctx: HttpContext): { limit?: number; offset?: number } {
-  return { limit: optionalInteger(ctx.query("limit"), "limit"), offset: optionalInteger(ctx.query("offset"), "offset") };
+/**
+ * The list query of a route: `filter[...]`, `sort`, `page[...]`; anything
+ * `options` does not list is 400. Each filter here names one service option, so
+ * OR groups and a field filtered twice are refused rather than half applied.
+ */
+export function listQuery(ctx: HttpContext, options: Pick<ListQueryOptions, "filter" | "sort">): ListQuery {
+  try {
+    const list = parseListQuery(ctx.url.searchParams, { ...options, page: { defaultSize: 50, maxSize: 200 } });
+    const problems: ListQueryProblem[] = list.or.length > 0 ? [{ parameter: "filter[or]", message: "OR groups are not supported here" }] : [];
+    for (const [index, { field }] of list.filters.entries()) {
+      if (list.filters.findIndex((rule) => rule.field === field) !== index) problems.push({ parameter: `filter[${field}]`, message: "the field is filtered twice" });
+    }
+    if (problems.length > 0) throw new ListQueryError(problems);
+    return list;
+  } catch (error) {
+    if (error instanceof ListQueryError) throw frameworkBadRequest("invalidListQuery", undefined, error.problems);
+    throw error;
+  }
+}
+
+/** The page and order of a list query, for a list operation. */
+export function pagingOfList(list: ListQuery): WorkflowPaging {
+  return { limit: list.page.limit, offset: list.page.offset, ...(list.sort.length === 0 ? {} : { sort: list.sort }) };
+}
+
+/** The value of `filter[field]`. */
+export function filterOf(list: ListQuery, field: string): string | undefined {
+  const value = list.filters.find((rule) => rule.field === field)?.value;
+  return Array.isArray(value) ? value.join(",") : value as string | undefined;
 }

package/core/workflow/runtime_module/WorkflowRuntime.module.ts

@@ -5,7 +5,6 @@ import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinit
 import { runtimePermissions } from "./access/Runtime.permissions";
 import { WorkflowRetention } from "./background/WorkflowRetention";
 import { WorkflowWorker } from "./background/WorkflowWorker";
-import { workflowRuntimeConfig } from "./config/Runtime.config";
 import { EventsController } from "./http/Events.controller";
 import { InstancesController } from "./http/Instances.controller";
 import { GraphCache } from "./internal/GraphCache";
@@ -25,7 +24,6 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
 @Module({
   imports: [AccessModule, WorkflowDefinitionsModule],
   permissions: runtimePermissions,
-  config: [workflowRuntimeConfig],
   ormBazis: { context: RuntimeDbContext, entities: [...RUNTIME_ENTITIES], ownedStore: runtimeStore, registerRepositories: false },
   providers: [
     singleton(GraphCache),

package/core/workflow/runtime_module/access/Runtime.permissions.ts

@@ -1,24 +1,26 @@
 import { definePermissions } from "../../../access";
+import { ProcessFolderLookup } from "../../definitions_module/access/ProcessFolder.lookup";
 
 const process = { ref: "workflow.process", column: "processKey" };
+const folder = { ref: "workflow.folder", lookup: ProcessFolderLookup };
 
 /** The rights of running processes (WORKFLOW-002 §6.2). */
 export const runtimePermissions = definePermissions({
   "workflow.instances.start": {
     title: { en: "Start processes", ru: "Запускать процессы" },
     scope: "request",
-    on: { process },
+    on: { process, folder },
   },
   "workflow.instances.read": {
     title: { en: "See instances", ru: "Видеть экземпляры" },
     scope: { column: "partition" },
-    on: { process },
+    on: { process, folder },
     owner: "startedById",
   },
   "workflow.instances.manage": {
     title: { en: "Cancel and retry instances", ru: "Отменять и повторять экземпляры" },
     scope: { column: "partition" },
-    on: { process },
+    on: { process, folder },
   },
   "workflow.events.emit": {
     title: { en: "Send events to processes", ru: "Отправлять события процессам" },