bazis 0.130.0 → 0.131.0

package/core/agent/AgentToolExecutor.ts

@@ -58,6 +58,8 @@ export interface AgentToolExecutionContext {
   readonly maxAttempts: number;
   readonly idempotencyKey?: string;
   readonly approval: AgentToolExecutionApproval;
+  /** On whose behalf the call runs, when the caller says so. */
+  readonly actor?: ToolActor;
   readonly metadata: JsonObject;
   readonly signal: AbortSignal;
 }
@@ -1664,6 +1666,7 @@ export class AgentToolExecutor {
       maxAttempts: attempt.maxAttempts,
       ...(attempt.idempotencyKey !== undefined ? { idempotencyKey: attempt.idempotencyKey } : {}),
       approval,
+      ...(options.actor !== undefined ? { actor: options.actor } : {}),
       metadata,
       signal,
     });

package/core/agent/Tool.contract.ts

@@ -15,6 +15,6 @@ export function describeTool(tool: ToolDefinition) {
     name: tool.metadata.name, description: tool.metadata.description,
     input: tool.metadata.input ? schema(tool.metadata.input) : undefined,
     output: tool.metadata.output ? schema(tool.metadata.output) : undefined,
-    sideEffect: tool.metadata.sideEffect, approval: tool.metadata.approval, timeoutMs: tool.metadata.timeoutMs,
+    sideEffect: tool.metadata.sideEffect, approval: tool.metadata.approval, timeoutMs: tool.metadata.timeoutMs, dryRun: tool.metadata.dryRun,
   });
 }

package/core/agent/index.ts

@@ -88,6 +88,7 @@ export {
   type ToolApproval,
   type ToolMetadata,
   type ToolActor,
+  type ToolDryRun,
   type ToolOptions,
   type ToolSideEffect,
 } from "./metadata";

package/core/agent/metadata.ts

@@ -15,6 +15,8 @@ export interface ToolActor {
   readonly id: string;
 }
 export type ToolApproval = "never" | "policy" | "required";
+/** Whether a Tool can run without changing anything, when a process is tried out (WORKFLOW-002 §5.4). */
+export type ToolDryRun = "supported" | "unsupported";
 
 export interface ToolOptions {
   readonly name: string;
@@ -24,6 +26,8 @@ export interface ToolOptions {
   readonly sideEffect?: ToolSideEffect;
   readonly approval?: ToolApproval;
   readonly timeoutMs?: number;
+  /** `"unsupported"` by default. */
+  readonly dryRun?: ToolDryRun;
   /**
    * Who may call the Tool: `"agent"` for LLM agents, any other id for code that
    * runs Tools itself (`ToolRunner.as("workflow")`). Required and non-empty;
@@ -42,6 +46,7 @@ export interface ToolMetadata {
   readonly sideEffect: ToolSideEffect;
   readonly approval: ToolApproval;
   readonly timeoutMs?: number;
+  readonly dryRun: ToolDryRun;
   readonly callers: readonly string[];
   readonly tags: readonly string[];
 }
@@ -103,6 +108,9 @@ export function defineToolMetadata(_target: object, metadata: object, options: T
   if (options.approval !== undefined && options.approval !== "never" && options.approval !== "policy" && options.approval !== "required") {
     throw new AgentSetupError("@Tool.approval must be never, policy or required.");
   }
+  if (options.dryRun !== undefined && options.dryRun !== "supported" && options.dryRun !== "unsupported") {
+    throw new AgentSetupError("@Tool.dryRun must be supported or unsupported.");
+  }
   const normalized: ToolMetadata = Object.freeze({
     name: text(options.name, "@Tool.name"),
     description: text(options.description, "@Tool.description"),
@@ -111,6 +119,7 @@ export function defineToolMetadata(_target: object, metadata: object, options: T
     sideEffect,
     approval: approvalFor(sideEffect, options.approval),
     timeoutMs: positiveInteger(options.timeoutMs, "@Tool.timeoutMs"),
+    dryRun: options.dryRun ?? "unsupported",
     // Checked when the module registers the Tool, so a missing list prints as
     // one configuration-error line at start instead of failing the import.
     callers: Array.isArray(options.callers) ? Object.freeze(options.callers.map((caller) => callerId(caller))) : Object.freeze([]),

package/core/agent/semantic.ts

@@ -1,5 +1,5 @@
 import { AgentSemanticError } from "./errors";
-import type { ToolApproval, ToolSideEffect } from "./metadata";
+import type { ToolApproval, ToolDryRun, ToolSideEffect } from "./metadata";
 
 const FORBIDDEN_JSON_KEYS = new Set(["__proto__", "prototype", "constructor"]);
 
@@ -162,6 +162,7 @@ export interface AgentToolContract {
   readonly sideEffect: ToolSideEffect;
   readonly approval: ToolApproval;
   readonly timeoutMs?: number;
+  readonly dryRun: ToolDryRun;
 }
 
 export interface AgentToolContractOptions {
@@ -172,6 +173,7 @@ export interface AgentToolContractOptions {
   readonly sideEffect?: ToolSideEffect;
   readonly approval?: ToolApproval;
   readonly timeoutMs?: number;
+  readonly dryRun?: ToolDryRun;
 }
 
 export interface AgentModelCapabilities {
@@ -533,6 +535,10 @@ export function agentToolContract(options: AgentToolContractOptions): AgentToolC
   if ((sideEffect === "write" || sideEffect === "external") && approval === "never") {
     throw new AgentSemanticError('write/external tools cannot use approval: "never".');
   }
+  const dryRun = options.dryRun ?? "unsupported";
+  if (dryRun !== "supported" && dryRun !== "unsupported") {
+    throw new AgentSemanticError("tool.dryRun must be supported or unsupported.");
+  }
   return freezeWithoutUndefined({
     name: requiredName(options.name, "tool.name"),
     description: requiredContentText(options.description, "tool.description"),
@@ -541,6 +547,7 @@ export function agentToolContract(options: AgentToolContractOptions): AgentToolC
     sideEffect,
     approval,
     timeoutMs: optionalPositiveInteger(options.timeoutMs, "tool.timeoutMs"),
+    dryRun,
   });
 }
 

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.130.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.131.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/contracts/types.ts

@@ -1,19 +1,42 @@
+import type { ListQuery, SortField } from "../../../library/jsonapi";
+
 /** Who acts: a user or the system (schedules, events). Steps of an instance run on behalf of who started it. */
 export interface WorkflowActor {
   readonly kind: "user" | "system";
   readonly id: string;
 }
 
+/** Where an action came from, for the audit: `null` in its place means code called. */
+export interface WorkflowRequest {
+  readonly ip: string | null;
+  readonly userAgent: string | null;
+}
+
+/** What the audit events of an action carry besides its actor. */
+export interface WorkflowAuditOptions {
+  readonly request?: WorkflowRequest | null;
+}
+
+/** What `context.metadata` holds when a process calls a Tool: enough to name the cause in its own events. */
+export interface WorkflowToolMetadata {
+  readonly instanceId: string;
+  readonly processKey: string;
+  readonly nodeId: string;
+  readonly partition: string | null;
+  readonly test: boolean;
+}
+
 /** A page of a list. */
 export interface WorkflowPage<T> {
   readonly items: readonly T[];
   readonly total: number;
 }
 
-/** Paging of the list operations: `limit` 1–200 (50 by default), `offset` from 0. */
+/** Paging of the list operations: `limit` 1–200 (50 by default), `offset` from 0; `sort` replaces the list's own order. */
 export interface WorkflowPaging {
   readonly limit?: number;
   readonly offset?: number;
+  readonly sort?: readonly SortField[];
 }
 
 export function pagingOf(paging: WorkflowPaging): { readonly limit: number; readonly offset: number } {
@@ -22,6 +45,19 @@ export function pagingOf(paging: WorkflowPaging): { readonly limit: number; read
   return { limit: Number.isFinite(limit) ? Math.min(Math.max(limit, 1), 200) : 50, offset: Number.isFinite(offset) ? Math.max(offset, 0) : 0 };
 }
 
+/** The page of a list operation as `paginate` takes it. */
+export function pageQueryOf(paging: WorkflowPaging, order: SortField): ListQuery {
+  const { limit, offset } = pagingOf(paging);
+  return {
+    sort: paging.sort ?? [order],
+    filters: [],
+    or: [],
+    include: [],
+    fields: {},
+    page: { limit, offset, size: limit, number: Math.floor(offset / limit) + 1 },
+  };
+}
+
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /** Whether an id can be a row key; anything else would reach PostgreSQL as an invalid uuid. */

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

@@ -1,6 +1,7 @@
 import { AccessModule } from "../../access";
 import { HOSTED_SERVICE, Module, scoped, singleton } from "../../di";
 import { SystemWorkflowClock, WorkflowClock } from "../contracts/WorkflowClock";
+import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { definitionsPermissions } from "./access/Definitions.permissions";
 import { ProcessReferences } from "./access/Process.references";
@@ -26,11 +27,12 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(WorkflowClock, SystemWorkflowClock),
     singleton(WorkflowTools),
     singleton(CodeProcessCatalog),
+    scoped(WorkflowEvents),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
     scoped(ProcessReferences),
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],
-  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock],
+  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/events/Definitions.events.ts

@@ -0,0 +1,16 @@
+import { createEventToken } from "../../../kernel";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
+
+export type ProcessChange = "created" | "updated" | "draftSaved" | "published" | "archived" | "restored";
+
+/** A process of the catalog changed, for the application's audit. Published after the commit. */
+export interface WorkflowProcessChanged {
+  readonly change: ProcessChange;
+  readonly key: string;
+  /** The version a `published` change made; otherwise `null`. */
+  readonly version: number | null;
+  readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest | null;
+}
+
+export const WORKFLOW_PROCESS_CHANGED = createEventToken<WorkflowProcessChanged>("workflow.process-changed");

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -1,7 +1,8 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
 import { can } from "../../../access";
 import { Authorize, Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
-import { body, callerOf, optionalInteger, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import { buildListDocument } from "../../../../library/jsonapi";
+import { body, callerOf, filterOf, listQuery, optionalInteger, optionalString, pagingOfList, param, requiredString } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 
@@ -14,10 +15,11 @@ export class ProcessesController {
   @Authorize(can("workflow.processes.read"))
   async list(ctx: HttpContext) {
     const { access } = await callerOf(ctx);
-    const archived = ctx.query("archived");
+    const list = listQuery(ctx, { filter: { archived: ["eq"], search: ["eq"] }, sort: ["key", "title", "createdAt", "updatedAt"] });
+    const archived = filterOf(list, "archived");
     if (archived !== undefined && archived !== "true" && archived !== "false") throw new WorkflowError("invalid_input", "archived must be true or false");
-    const page = await this.definitions.list({ ...pagingQuery(ctx), access: await access.filter("workflow.processes.read"), archived: archived === undefined ? undefined : archived === "true", search: optionalString(ctx.query("search"), "search") });
-    return { data: page.items, meta: { total: page.total } };
+    const page = await this.definitions.list({ ...pagingOfList(list), access: await access.filter("workflow.processes.read"), archived: archived === undefined ? undefined : archived === "true", search: filterOf(list, "search") });
+    return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
   }
 
   @Post("processes")
@@ -25,13 +27,13 @@ export class ProcessesController {
   async create(ctx: HttpContext) {
     const request = await body(ctx);
     const key = requiredString(request.key, "key", 64);
-    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     const process = await this.definitions.create({
       key,
       title: requiredString(request.title, "title"),
       description: optionalString(request.description, "description", 2000) ?? null,
       retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null,
-    }, actor);
+    }, actor, { request: from });
     return Created(`${ctx.path}/${process.key}`, process);
   }
 
@@ -48,14 +50,14 @@ export class ProcessesController {
   async update(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     if (request.archived !== undefined && typeof request.archived !== "boolean") throw new WorkflowError("invalid_input", "archived must be a boolean");
     return await this.definitions.update(key, {
       ...(request.title === undefined ? {} : { title: requiredString(request.title, "title") }),
       ...(request.description === undefined ? {} : { description: optionalString(request.description, "description", 2000) ?? null }),
       ...(request.retentionDays === undefined ? {} : { retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null }),
       ...(request.archived === undefined ? {} : { archived: request.archived as boolean }),
-    }, actor);
+    }, actor, { request: from });
   }
 
   @Put("processes/:key/draft")
@@ -63,16 +65,19 @@ export class ProcessesController {
   async saveDraft(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
-    return await this.definitions.saveDraft(key, request.document, actor);
+    const { actor, request: from } = await callerOf(ctx, "workflow.processes.manage", { process: key });
+    const expected = optionalString(request.expected, "expected");
+    const expectedAt = expected === undefined ? undefined : new Date(expected);
+    if (expectedAt !== undefined && Number.isNaN(expectedAt.getTime())) throw new WorkflowError("invalid_input", "expected must be the draftUpdatedAt that was read");
+    return await this.definitions.saveDraft(key, request.document, actor, { request: from, ...(expectedAt === undefined ? {} : { expected: expectedAt }) });
   }
 
   @Post("processes/:key/publish")
   @Authorize(can("workflow.processes.publish"))
   async publish(ctx: HttpContext) {
     const key = param(ctx, "key");
-    const { actor } = await callerOf(ctx, "workflow.processes.publish", { process: key });
-    const version = await this.definitions.publish(key, actor);
+    const { actor, request } = await callerOf(ctx, "workflow.processes.publish", { process: key });
+    const version = await this.definitions.publish(key, actor, { request });
     return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
   }
 

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

@@ -1,7 +1,7 @@
 import type { AccessFilter } from "../../../access";
 import type { AgentToolContract } from "../../../agent";
 import type { ProcessDocument, ProcessIssue } from "../../../../library/workflow";
-import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
 
 export interface ProcessSummary {
@@ -61,6 +61,18 @@ export interface ProcessListQuery extends WorkflowPaging {
   readonly search?: string;
 }
 
+export interface SaveDraftOptions extends WorkflowAuditOptions {
+  /** The `draftUpdatedAt` the caller read: another save since then is `conflict`. Without it the last save wins. */
+  readonly expected?: Date;
+}
+
+export interface SavedDraft {
+  /** Every validation finding: a draft is stored with errors too. */
+  readonly issues: readonly ProcessIssue[];
+  /** Goes to `expected` of the next save. */
+  readonly draftUpdatedAt: Date;
+}
+
 /**
  * The process catalog: drafts and immutable published versions
  * (WORKFLOW-001 §3). Errors are {@link WorkflowError}: `not_found`, `conflict`,
@@ -69,16 +81,16 @@ export interface ProcessListQuery extends WorkflowPaging {
 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>;
+  abstract create(process: CreateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): 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; `conflict` for a process declared in code. */
-  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }>;
+  abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<ProcessDetails>;
+  /** Stores the draft even with errors; `conflict` for a process declared in code and when `expected` is out of date. */
+  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor, options?: SaveDraftOptions): Promise<SavedDraft>;
   /**
    * 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 publish(key: string, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<VersionDetails>;
   abstract versions(key: string): Promise<readonly VersionSummary[]>;
   abstract version(key: string, version: number): Promise<VersionDetails>;
   /** The latest published version of a process that is not archived. */

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

@@ -1,14 +1,16 @@
 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 { isUuid, pageQueryOf, type WorkflowActor, type WorkflowAuditOptions, type WorkflowPage } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import { WorkflowError } from "../../contracts/WorkflowError";
+import type { WorkflowEvents } from "../../internal/WorkflowEvents";
 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,6 +20,8 @@ import {
   type ProcessDetails,
   type ProcessListQuery,
   type ProcessSummary,
+  type SavedDraft,
+  type SaveDraftOptions,
   type UpdateProcess,
   type VersionDetails,
   type VersionSummary,
@@ -33,12 +37,12 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     private readonly workflowTools: WorkflowTools,
     private readonly code: CodeProcessCatalog,
     private readonly clock: WorkflowClock,
+    private readonly events: WorkflowEvents,
   ) {
     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();
@@ -49,16 +53,15 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       const text = query.search.trim();
       source = source.where((p) => p.key.contains(text, { ignoreCase: true }).or(p.title.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 };
+    const { items, total } = await paginate(source, pageQueryOf(query, { 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 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,
@@ -77,43 +80,57 @@ 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);
+    const before = { title: row.title, description: row.description, retentionDays: row.retentionDays, archived: row.archivedAt !== null };
     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 (archived !== undefined) row.archivedAt = archived ? row.archivedAt ?? this.clock.now() : null;
     await this.db.saveChanges();
+    if (row.title !== before.title || row.description !== before.description || row.retentionDays !== before.retentionDays) 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[] }> {
+  async saveDraft(key: string, document: unknown, actor: WorkflowActor, options: SaveDraftOptions = {}): Promise<SavedDraft> {
     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 = 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 = {}): 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);
       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 +141,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,6 +149,7 @@ 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;
@@ -149,6 +167,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 +245,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);

package/core/workflow/generated/deps.ts

@@ -12,6 +12,7 @@ import { ProcessesController } from "../definitions_module/http/Processes.contro
 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 { WorkflowTools } from "../internal/WorkflowTools";
 import { WorkflowRetention } from "../runtime_module/background/WorkflowRetention";
 import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
@@ -46,11 +47,12 @@ 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]],
+  [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
+  [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
   [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
   [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider]],
-  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock]],
+  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock, WorkflowEvents]],
   [WorkflowTools, [ServiceProvider]],
   [WorkflowWorker, [ServiceProvider, "Config:workflow"]],
 ]);

package/core/workflow/index.ts

@@ -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,27 +23,37 @@ export {
   type ProcessDetails,
   type ProcessListQuery,
   type ProcessSummary,
+  type SavedDraft,
+  type SaveDraftOptions,
   type UpdateProcess,
   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,
@@ -52,7 +64,7 @@ export type { InstanceStatus, StartedVia } from "./runtime_module/model/WfInstan
 export type { TokenStatus } from "./runtime_module/model/WfToken.model";
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
 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) });
+    }
+  }
+}