bazis 0.126.0 → 0.128.0

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

@@ -0,0 +1,85 @@
+import {
+  createModuleOwnedMetadataChannel,
+  registerModuleOwnedContributionValidator,
+  registerModuleOwnedProviderContributor,
+  DiContainer,
+  type BazisModuleMetadata,
+  type ServiceProvider,
+} from "../../../di";
+import { validateProcess, type ProcessIssue } from "../../../../library/workflow";
+import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
+import { isCodeProcess, type CodeProcess } from "./defineProcess";
+
+/** A process of `@Module({ processes })` with the module that declares it. */
+export interface OwnedCodeProcess {
+  readonly process: CodeProcess;
+  readonly module: string;
+}
+
+const PROCESS_CHANNEL = createModuleOwnedMetadataChannel<CodeProcess>("workflow.process/v1");
+const KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+
+/** A problem of the processes declared in code; the application reports it as a configuration error. */
+export class WorkflowSetupError extends Error {
+  override readonly name = "WorkflowSetupError";
+}
+
+// Internal imports must not depend on the public barrel having augmented DI's metadata interface.
+interface WorkflowModuleFields {
+  readonly processes?: readonly unknown[];
+}
+
+registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context) => {
+  const processes = (metadata as BazisModuleMetadata & WorkflowModuleFields).processes;
+  if (processes === undefined) return;
+  const module = moduleName(metadata);
+  if (!Array.isArray(processes)) throw new WorkflowSetupError(`${module}: processes must be an array of defineProcess(...) results.`);
+  for (const process of processes) {
+    if (!isCodeProcess(process)) throw new WorkflowSetupError(`${module}: processes must list defineProcess(...) results.`);
+    const problems = definitionProblems(process);
+    if (problems.length > 0) throw new WorkflowSetupError(`${module}: process "${process.key}" ${problems.length === 1 ? "has an error" : "has errors"}:\n${problems.map((line) => `  - ${line}`).join("\n")}`);
+    context.addMetadata(PROCESS_CHANNEL, process);
+  }
+});
+
+registerModuleOwnedContributionValidator((snapshot) => {
+  const contributions = snapshot.getMetadataContributions(PROCESS_CHANNEL);
+  if (contributions.length === 0) return;
+  const owners = new Map<string, string>();
+  for (const { payload, ownerName } of contributions) {
+    const other = owners.get(payload.key);
+    if (other !== undefined) throw new WorkflowSetupError(`Process "${payload.key}" is declared twice: in ${other} and in ${ownerName}.`);
+    owners.set(payload.key, ownerName);
+  }
+  if (snapshot.countProviders(IWorkflowDefinitions) === 0) {
+    throw new WorkflowSetupError(`${contributions[0]!.ownerName} declares processes, but the application does not import WorkflowModule (bazis/core/workflow).`);
+  }
+});
+
+/** The processes declared in the modules of the application's container. */
+export function codeProcessesOf(services: ServiceProvider): readonly OwnedCodeProcess[] {
+  if (!(services instanceof DiContainer)) throw new WorkflowSetupError("Processes declared in code require the framework DiContainer.");
+  return services.getModuleOwnedMetadataContributions(PROCESS_CHANNEL).map(({ payload, ownerName }) => ({ process: payload, module: ownerName }));
+}
+
+/** What is wrong with a definition before the Tools are known: the catalog fields and the document's errors. */
+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");
+  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;
+}
+
+function documentErrors(issues: readonly ProcessIssue[]): string[] {
+  return issues.filter((issue) => issue.severity === "error").map((issue) => {
+    const at = issue.node !== undefined ? `node ${issue.node}: ` : issue.flow !== undefined ? `flow ${issue.flow}: ` : "";
+    return `${at}${issue.message} (${issue.code})`;
+  });
+}
+
+function moduleName(metadata: BazisModuleMetadata): string {
+  return typeof metadata === "function" ? (metadata as { name: string }).name || "<anonymous module>" : "<module>";
+}

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

@@ -0,0 +1,40 @@
+import type { ProcessDocument } from "../../../../library/workflow";
+
+const CODE_PROCESS = Symbol.for("bazis/core/workflow/code-process");
+
+/** What `defineProcess` takes: the catalog fields of the process and its document. */
+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;
+  /** Days to keep completed and cancelled instances; omitted keeps them. */
+  readonly retentionDays?: number | null;
+  readonly document: ProcessDocument;
+}
+
+/** A process described in code: listed in `@Module({ processes })` and published at start (WORKFLOW-001 §14). */
+export interface CodeProcess extends ProcessDefinition {
+  readonly [CODE_PROCESS]: true;
+}
+
+/**
+ * Describes a process in the code of the module that owns it. It is only a
+ * description: checks happen when the container is built and at start.
+ *
+ * ```ts
+ * // orders_module/processes/OrderApproval.process.ts
+ * export const OrderApprovalProcess = defineProcess({
+ *   key: "order-approval",
+ *   title: "Order approval",
+ *   document: { schemaVersion: "bazis.workflow/v1", nodes: { … }, flows: { … } },
+ * });
+ * ```
+ */
+export function defineProcess(definition: ProcessDefinition): CodeProcess {
+  return Object.freeze({ ...definition, [CODE_PROCESS]: true as const });
+}
+
+export function isCodeProcess(value: unknown): value is CodeProcess {
+  return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[CODE_PROCESS] === true;
+}

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

@@ -0,0 +1,74 @@
+import { expandModuleMetadata, type BazisModuleRef } from "../../../di";
+import { toolMetadataOf } from "../../../agent";
+import { validateProcess } from "../../../../library/workflow";
+import { WORKFLOW_CALLER } from "../../internal/WorkflowTools";
+import { WorkflowDefinitionsModule } from "../WorkflowDefinitions.module";
+import { definitionProblems, type OwnedCodeProcess } from "./codeProcesses";
+import { isCodeProcess } from "./defineProcess";
+
+/** What `bazis workflow check` reports for one process. */
+export interface InspectedProcess extends OwnedCodeProcess {
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export interface ProcessInspection {
+  readonly processes: readonly InspectedProcess[];
+  /** Problems across processes: one key in two modules, a `processes` entry that is not a process. */
+  readonly errors: readonly string[];
+  /** Tools of the module tree that processes may call. */
+  readonly tools: readonly string[];
+}
+
+/**
+ * The processes and Tools of a module tree without building the application
+ * (`bazis workflow check`): the checks of the build and of the start at once.
+ */
+export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
+  const found: OwnedCodeProcess[] = [];
+  const errors: string[] = [];
+  const tools = new Set<string>();
+  const visited = new Set<BazisModuleRef>();
+  const visit = (moduleRef: BazisModuleRef): void => {
+    if (visited.has(moduleRef)) return;
+    visited.add(moduleRef);
+    const module = typeof moduleRef === "function" ? moduleRef.name || "<anonymous module>" : "<module>";
+    const fields = moduleRef as { readonly processes?: unknown; readonly tools?: unknown };
+    if (Array.isArray(fields.tools)) {
+      for (const target of fields.tools) {
+        const metadata = typeof target === "function" ? toolMetadataOf(target as new () => object) : undefined;
+        if (metadata?.callers.includes(WORKFLOW_CALLER)) tools.add(metadata.name);
+      }
+    }
+    if (fields.processes !== undefined) {
+      if (!Array.isArray(fields.processes)) errors.push(`${module}: processes must be an array of defineProcess(...) results.`);
+      else for (const process of fields.processes) {
+        if (isCodeProcess(process)) found.push({ process, module });
+        else errors.push(`${module}: processes must list defineProcess(...) results.`);
+      }
+    }
+    for (const imported of moduleRef.imports ?? []) visit(imported);
+    for (const expanded of expandModuleMetadata(moduleRef)) visit(expanded);
+  };
+  visit(root);
+  if (found.length > 0 && !visited.has(WorkflowDefinitionsModule)) {
+    errors.push(`${found[0]!.module} declares processes, but the application does not import WorkflowModule (bazis/core/workflow).`);
+  }
+  const owners = new Map<string, string>();
+  for (const { process, module } of found) {
+    const other = owners.get(process.key);
+    if (other !== undefined) errors.push(`Process "${process.key}" is declared twice: in ${other} and in ${module}.`);
+    else owners.set(process.key, module);
+  }
+  const allowed = (name: string) => tools.has(name);
+  return {
+    processes: found.map((entry) => ({
+      ...entry,
+      errors: definitionProblems(entry.process, allowed),
+      warnings: validateProcess(entry.process.document, { tools: allowed }).filter((issue) => issue.severity === "warning")
+        .map((issue) => `${issue.node !== undefined ? `node ${issue.node}: ` : issue.flow !== undefined ? `flow ${issue.flow}: ` : ""}${issue.message} (${issue.code})`),
+    })),
+    errors,
+    tools: [...tools].sort(),
+  };
+}

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

@@ -9,6 +9,11 @@ export interface ProcessSummary {
   readonly latestVersion: number | null;
   readonly retentionDays: number | null;
   readonly archived: boolean;
+  /**
+   * The module whose `@Module({ processes })` declares it; such a process
+   * changes only through the code (WORKFLOW-001 §14). `null` for the catalog's own.
+   */
+  readonly module: string | null;
   readonly createdAt: Date;
   readonly updatedAt: Date;
 }
@@ -61,10 +66,14 @@ export abstract class IWorkflowDefinitions {
   abstract list(query?: ProcessListQuery): Promise<WorkflowPage<ProcessSummary>>;
   abstract get(key: string): Promise<ProcessDetails>;
   abstract create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
+  /** A process declared in code takes only `archived`; other fields give `conflict`. */
   abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
-  /** Stores the draft even with errors and returns every validation finding. */
+  /** Stores the draft even with errors and returns every validation finding; `conflict` for a process declared in code. */
   abstract saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }>;
-  /** Validates the draft and stores it as the next version; the same document again returns the latest version. */
+  /**
+   * Validates the draft and stores it as the next version; the same document
+   * again returns the latest version. `conflict` for a process declared in code.
+   */
   abstract publish(key: string, actor: WorkflowActor): Promise<VersionDetails>;
   abstract versions(key: string): Promise<readonly VersionSummary[]>;
   abstract version(key: string, version: number): Promise<VersionDetails>;

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

@@ -3,8 +3,11 @@ import { 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 type { WorkflowClock } from "../../contracts/WorkflowClock";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
+import type { CodeProcessCatalog } from "../code/CodeProcessCatalog";
+import type { OwnedCodeProcess } from "../code/codeProcesses";
 import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
 import { WfProcess } from "../model/WfProcess.model";
 import { WfVersion } from "../model/WfVersion.model";
@@ -20,11 +23,15 @@ import {
 } from "./IWorkflowDefinitions.service";
 
 const KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+/** Who publishes the processes declared in code. */
+const CODE_ACTOR: WorkflowActor = { kind: "system", id: "code" };
 
 export class WorkflowDefinitions extends IWorkflowDefinitions {
   constructor(
     private readonly db: DefinitionsDbContext,
     private readonly workflowTools: WorkflowTools,
+    private readonly code: CodeProcessCatalog,
+    private readonly clock: WorkflowClock,
   ) {
     super();
   }
@@ -40,11 +47,11 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     }
     const total = await source.count();
     const rows = await source.orderBy((p) => p.key).skip(offset).take(limit).toList();
-    return { items: rows.map(summaryOf), total };
+    return { items: rows.map((row) => this.summaryOf(row)), total };
   }
 
   async get(key: string): Promise<ProcessDetails> {
-    return detailsOf(await this.process(key, false));
+    return this.detailsOf(await this.process(key, false));
   }
 
   async create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails> {
@@ -55,7 +62,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       description: description(process.description),
       retentionDays: retention(process.retentionDays),
       draft: emptyProcess(),
-      draftUpdatedAt: new Date(),
+      draftUpdatedAt: this.clock.now(),
       draftUpdatedByKind: actor.kind,
       draftUpdatedById: actor.id,
     });
@@ -66,25 +73,28 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       if (error instanceof UniqueViolationError) throw new WorkflowError("conflict", `Process ${process.key} already exists`);
       throw error;
     }
-    return detailsOf(row);
+    return this.detailsOf(row);
   }
 
   async update(key: string, changes: UpdateProcess, _actor: WorkflowActor): 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);
     if (changes.description !== undefined) row.description = description(changes.description);
     if (changes.retentionDays !== undefined) row.retentionDays = retention(changes.retentionDays);
-    if (changes.archived !== undefined) row.archivedAt = changes.archived ? row.archivedAt ?? new Date() : null;
+    if (archived !== undefined) row.archivedAt = archived ? row.archivedAt ?? this.clock.now() : null;
     await this.db.saveChanges();
-    return detailsOf(row);
+    return this.detailsOf(row);
   }
 
   async saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }> {
     const issues = this.validate(document);
     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 = new Date();
+    row.draftUpdatedAt = this.clock.now();
     row.draftUpdatedByKind = actor.kind;
     row.draftUpdatedById = actor.id;
     await this.db.saveChanges();
@@ -95,27 +105,71 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return await this.db.transactionScope(async () => {
       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);
       if (hasErrors(issues)) throw new WorkflowError("invalid_document", `Process ${key} has errors and cannot be published`, issues);
-      const hash = createHash("sha256").update(canonicalJson(row.draft)).digest("hex");
-      if (row.latestVersion !== null) {
-        const latest = await this.db.versions.asNoTracking().firstOrDefault((v) => v.processId.eq(row.id).and(v.version.eq(row.latestVersion!)));
-        if (latest?.documentHash === hash) return versionOf(row.key, latest);
+      return (await this.publishDraft(row, actor)).version;
+    });
+  }
+
+  /**
+   * Brings the processes declared in code into the catalog (WORKFLOW-001 §14):
+   * creates or updates each, puts its document into the draft and publishes it,
+   * under one lock across application instances. Archived ones stay archived
+   * 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 () => {
+      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))) {
+        let row = await this.db.processes.where((p) => p.key.eq(process.key)).forUpdate().firstOrDefault();
+        if (!row) {
+          row = Object.assign(new WfProcess(), { key: process.key });
+          this.db.processes.add(row);
+        }
+        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;
+        if (row.retentionDays !== fields.retentionDays) row.retentionDays = fields.retentionDays;
+        if (row.draft === null || canonicalJson(row.draft) !== canonicalJson(process.document)) {
+          row.draft = process.document;
+          row.draftUpdatedAt = this.clock.now();
+          row.draftUpdatedByKind = CODE_ACTOR.kind;
+          row.draftUpdatedById = CODE_ACTOR.id;
+        }
+        await this.db.saveChanges();
+        if (row.archivedAt !== null) {
+          results.push({ key: row.key, version: row.latestVersion, published: false });
+          continue;
+        }
+        const { version, created } = await this.publishDraft(row, CODE_ACTOR);
+        results.push({ key: row.key, version: version.version, published: created });
       }
-      const version = Object.assign(new WfVersion(), {
-        processId: row.id,
-        version: (row.latestVersion ?? 0) + 1,
-        document: row.draft,
-        documentHash: hash,
-        publishedByKind: actor.kind,
-        publishedById: actor.id,
-      });
-      this.db.versions.add(version);
-      row.latestVersion = version.version;
-      await this.db.saveChanges();
-      return versionOf(row.key, version);
+      return results;
+    });
+  }
+
+  /** Stores the draft of a locked row as the next version, unless it is the latest one already. */
+  private async publishDraft(row: WfProcess, actor: WorkflowActor): Promise<{ readonly version: VersionDetails; readonly created: boolean }> {
+    const hash = createHash("sha256").update(canonicalJson(row.draft)).digest("hex");
+    if (row.latestVersion !== null) {
+      const latest = await this.db.versions.asNoTracking().firstOrDefault((v) => v.processId.eq(row.id).and(v.version.eq(row.latestVersion!)));
+      if (latest?.documentHash === hash) return { version: versionOf(row.key, latest), created: false };
+    }
+    const version = Object.assign(new WfVersion(), {
+      processId: row.id,
+      version: (row.latestVersion ?? 0) + 1,
+      document: row.draft,
+      documentHash: hash,
+      publishedByKind: actor.kind,
+      publishedById: actor.id,
     });
+    this.db.versions.add(version);
+    row.latestVersion = version.version;
+    await this.db.saveChanges();
+    return { version: versionOf(row.key, version), created: true };
   }
 
   async versions(key: string): Promise<readonly VersionSummary[]> {
@@ -168,6 +222,35 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return this.workflowTools.list();
   }
 
+  /** A process declared in code changes only through the code. */
+  private assertNotCode(key: string): void {
+    const module = this.code.moduleOf(key);
+    if (module !== undefined) throw new WorkflowError("conflict", `Process ${key} is declared in code by ${module} and changes only there`);
+  }
+
+  private summaryOf(row: WfProcess): ProcessSummary {
+    return {
+      key: row.key,
+      title: row.title,
+      description: row.description,
+      latestVersion: row.latestVersion,
+      retentionDays: row.retentionDays,
+      archived: row.archivedAt !== null,
+      module: this.code.moduleOf(row.key) ?? null,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+
+  private detailsOf(row: WfProcess): ProcessDetails {
+    return {
+      ...this.summaryOf(row),
+      draft: row.draft,
+      draftUpdatedAt: row.draftUpdatedAt,
+      draftUpdatedBy: row.draftUpdatedById === null ? null : { kind: row.draftUpdatedByKind === "system" ? "system" : "user", id: row.draftUpdatedById },
+    };
+  }
+
   private validate(document: unknown): ProcessIssue[] {
     return validateProcess(document, { tools: (name) => this.workflowTools.has(name) });
   }
@@ -201,28 +284,6 @@ function retention(value: unknown): number | null {
   return value as number;
 }
 
-function summaryOf(row: WfProcess): ProcessSummary {
-  return {
-    key: row.key,
-    title: row.title,
-    description: row.description,
-    latestVersion: row.latestVersion,
-    retentionDays: row.retentionDays,
-    archived: row.archivedAt !== null,
-    createdAt: row.createdAt,
-    updatedAt: row.updatedAt,
-  };
-}
-
-function detailsOf(row: WfProcess): ProcessDetails {
-  return {
-    ...summaryOf(row),
-    draft: row.draft,
-    draftUpdatedAt: row.draftUpdatedAt,
-    draftUpdatedBy: row.draftUpdatedById === null ? null : { kind: row.draftUpdatedByKind === "system" ? "system" : "user", id: row.draftUpdatedById },
-  };
-}
-
 function versionOf(key: string, row: WfVersion): VersionDetails {
   return {
     id: row.id,

package/core/workflow/index.ts

@@ -3,9 +3,17 @@
  * with the Definitions and Runtime parts, their services, HTTP, events and
  * extension points. The document format is `bazis/library/workflow`.
  */
+import type { CodeProcess } from "./definitions_module/code/defineProcess";
+
 export { WorkflowModule } from "./Workflow.module";
+export { defineProcess, type CodeProcess, type ProcessDefinition } from "./definitions_module/code/defineProcess";
+export { WorkflowSetupError } from "./definitions_module/code/codeProcesses";
+export { WorkflowClock, SystemWorkflowClock } from "./contracts/WorkflowClock";
 export { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefinitions.module";
 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 type { TaskStatus } from "./tasks_module/model/WfTask.model";
 export {
   IWorkflowDefinitions,
   type CreateProcess,
@@ -18,6 +26,8 @@ export {
 } from "./definitions_module/services/IWorkflowDefinitions.service";
 export {
   IWorkflowRuntime,
+  type EmitOptions,
+  type EmitResult,
   type HistoryEntry,
   type InstanceDetails,
   type InstanceListQuery,
@@ -27,9 +37,11 @@ export {
 } from "./runtime_module/services/IWorkflowRuntime.service";
 export {
   WORKFLOW_INSTANCE_FINISHED,
+  WORKFLOW_INSTANCES_DELETED,
   WORKFLOW_TASK_REQUESTED,
   WORKFLOW_TOKEN_CLOSED,
   type WorkflowInstanceFinished,
+  type WorkflowInstancesDeleted,
   type WorkflowTaskRequested,
   type WorkflowTokenClosed,
 } from "./runtime_module/events/Runtime.events";
@@ -41,3 +53,12 @@ export { WorkflowAccess, DenyWorkflowAccess, type WorkflowAccessTarget, type Wor
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
 export type { WorkflowActor, WorkflowPage, WorkflowPaging } 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.
+declare module "../di/module/types/BazisModule" {
+  interface BazisModuleMetadata {
+    /** Processes of the module, from `defineProcess`: published at start (WORKFLOW-001 §14). */
+    readonly processes?: readonly CodeProcess[];
+  }
+}

package/core/workflow/internal/http.ts

@@ -16,6 +16,12 @@ export async function authorize(ctx: HttpContext, action: WorkflowAction, target
   return actor;
 }
 
+/** Whom the caller's tasks are addressed to, from the application's {@link WorkflowAccess}. */
+export async function assigneesOf(ctx: HttpContext, actor: WorkflowActor): Promise<readonly string[]> {
+  const access = ctx.services.tryResolve(WorkflowAccess);
+  return access === undefined ? [] : await access.assignees(ctx, actor);
+}
+
 /** A route parameter as a string. */
 export function param(ctx: HttpContext, name: string): string {
   return String(ctx.params[name] ?? "");

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

@@ -1,5 +1,6 @@
 import { DI, Module, SERVICE_PROVIDER, scoped } from "../../di";
 import { EventBus, LOGGER } from "../../kernel";
+import { WorkflowClock } from "../contracts/WorkflowClock";
 import { DefaultWorkflowInputValidator, WorkflowInputValidator } from "../contracts/WorkflowInputValidator";
 import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
 import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
@@ -36,6 +37,7 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
       resolver.resolve(EventBus),
       resolver,
       resolver.tryResolve(LOGGER),
+      resolver.resolve(WorkflowClock),
     ))),
     scoped(ToolStep, ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools] as const),
     scoped(TimerStep, TimerStep, [RuntimeDbContext, WorkflowEngine] as const),

package/core/workflow/runtime_module/background/WorkflowRetention.ts

@@ -1,7 +1,9 @@
 import { BackgroundService, delay } from "../../../background";
 import type { ServiceProvider } from "../../../di";
-import type { ConfigView } from "../../../kernel";
+import { EventBus, type ConfigView } from "../../../kernel";
+import { WorkflowClock } from "../../contracts/WorkflowClock";
 import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import { WORKFLOW_INSTANCES_DELETED } from "../events/Runtime.events";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WorkflowSettings } from "./WorkflowWorker";
 
@@ -11,6 +13,8 @@ const DAY_MS = 86_400_000;
  * Deletes `completed` and `cancelled` instances older than their process's
  * `retentionDays`, with tokens, jobs, subscriptions and history (by cascade),
  * `retention.batchSize` at a time. `failed` instances wait for a person and stay.
+ * Each deleted batch is published as `WORKFLOW_INSTANCES_DELETED`, so parts
+ * with their own data (tasks) drop theirs.
  */
 export class WorkflowRetention extends BackgroundService {
   constructor(
@@ -21,7 +25,7 @@ export class WorkflowRetention extends BackgroundService {
   }
 
   protected override async execute(signal: AbortSignal): Promise<void> {
-    if (!this.config.get("retention.enabled")) return;
+    if (!this.config.get("retention.enabled") || this.services.resolve(WorkflowClock).manual === true) return;
     const intervalMs = this.config.get("retention.intervalMs");
     while (!signal.aborted) {
       try {
@@ -42,8 +46,9 @@ export class WorkflowRetention extends BackgroundService {
     try {
       const definitions = scope.resolve(IWorkflowDefinitions);
       const db = scope.resolve(RuntimeDbContext);
+      const now = scope.resolve(WorkflowClock).now().getTime();
       for (const policy of await definitions.retentionPolicies()) {
-        const cutoff = new Date(Date.now() - policy.retentionDays * DAY_MS);
+        const cutoff = new Date(now - policy.retentionDays * DAY_MS);
         for (;;) {
           if (signal?.aborted) return deleted;
           const ids = (await db.instances.asNoTracking()
@@ -55,6 +60,7 @@ export class WorkflowRetention extends BackgroundService {
           if (ids.length === 0) break;
           await db.instances.asNoTracking().where((i) => i.id.in(ids)).executeDelete();
           deleted += ids.length;
+          await scope.resolve(EventBus).publishScoped(scope, WORKFLOW_INSTANCES_DELETED, { instanceIds: ids });
           if (ids.length < batchSize) break;
         }
       }