bazis 0.123.0 → 0.124.1

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

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+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 { WorkflowError } from "../../contracts/WorkflowError";
+import type { WorkflowTools } from "../../internal/WorkflowTools";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+import { WfProcess } from "../model/WfProcess.model";
+import { WfVersion } from "../model/WfVersion.model";
+import {
+  IWorkflowDefinitions,
+  type CreateProcess,
+  type ProcessDetails,
+  type ProcessListQuery,
+  type ProcessSummary,
+  type UpdateProcess,
+  type VersionDetails,
+  type VersionSummary,
+} from "./IWorkflowDefinitions.service";
+
+const KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+
+export class WorkflowDefinitions extends IWorkflowDefinitions {
+  constructor(
+    private readonly db: DefinitionsDbContext,
+    private readonly workflowTools: WorkflowTools,
+  ) {
+    super();
+  }
+
+  async list(query: ProcessListQuery = {}): Promise<WorkflowPage<ProcessSummary>> {
+    const { limit, offset } = pagingOf(query);
+    let source = this.db.processes.asNoTracking();
+    if (query.archived === true) source = source.where((p) => p.archivedAt.isNotNull());
+    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 })));
+    }
+    const total = await source.count();
+    const rows = await source.orderBy((p) => p.key).skip(offset).take(limit).toList();
+    return { items: rows.map(summaryOf), total };
+  }
+
+  async get(key: string): Promise<ProcessDetails> {
+    return detailsOf(await this.process(key, false));
+  }
+
+  async create(process: CreateProcess, actor: WorkflowActor): 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),
+      description: description(process.description),
+      retentionDays: retention(process.retentionDays),
+      draft: emptyProcess(),
+      draftUpdatedAt: new Date(),
+      draftUpdatedByKind: actor.kind,
+      draftUpdatedById: actor.id,
+    });
+    this.db.processes.add(row);
+    try {
+      await this.db.saveChanges();
+    } catch (error) {
+      if (error instanceof UniqueViolationError) throw new WorkflowError("conflict", `Process ${process.key} already exists`);
+      throw error;
+    }
+    return detailsOf(row);
+  }
+
+  async update(key: string, changes: UpdateProcess, _actor: WorkflowActor): Promise<ProcessDetails> {
+    const row = await this.process(key, true);
+    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;
+    await this.db.saveChanges();
+    return 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);
+    row.draft = document;
+    row.draftUpdatedAt = new Date();
+    row.draftUpdatedByKind = actor.kind;
+    row.draftUpdatedById = actor.id;
+    await this.db.saveChanges();
+    return { issues };
+  }
+
+  async publish(key: string, actor: WorkflowActor): Promise<VersionDetails> {
+    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);
+      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);
+      }
+      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);
+    });
+  }
+
+  async versions(key: string): Promise<readonly VersionSummary[]> {
+    const row = await this.process(key, false);
+    const rows = await this.db.versions.asNoTracking().where((v) => v.processId.eq(row.id)).orderByDescending((v) => v.version).toList();
+    return rows.map((version) => {
+      const { document: _document, ...summary } = versionOf(row.key, version);
+      return summary;
+    });
+  }
+
+  async version(key: string, version: number): Promise<VersionDetails> {
+    const row = await this.process(key, false);
+    const found = await this.db.versions.asNoTracking().firstOrDefault((v) => v.processId.eq(row.id).and(v.version.eq(version)));
+    if (!found) throw new WorkflowError("not_found", `Process ${key} has no version ${version}`);
+    return versionOf(row.key, found);
+  }
+
+  async latest(key: string): Promise<VersionDetails> {
+    const row = await this.process(key, false);
+    if (row.archivedAt !== null) throw new WorkflowError("archived", `Process ${key} is archived`);
+    if (row.latestVersion === null) throw new WorkflowError("not_found", `Process ${key} has no published version`);
+    return await this.version(key, row.latestVersion);
+  }
+
+  async versionById(id: string): Promise<VersionDetails | undefined> {
+    if (!isUuid(id)) return undefined;
+    const version = await this.db.versions.asNoTracking().firstOrDefault((v) => v.id.eq(id));
+    if (!version) return undefined;
+    const process = await this.db.processes.asNoTracking().firstOrDefault((p) => p.id.eq(version.processId));
+    return process ? versionOf(process.key, version) : undefined;
+  }
+
+  async retentionPolicies(): Promise<readonly { readonly key: string; readonly retentionDays: number }[]> {
+    const rows = await this.db.processes.asNoTracking().where((p) => p.retentionDays.isNotNull()).toList();
+    return rows.map((row) => ({ key: row.key, retentionDays: row.retentionDays! }));
+  }
+
+  tools(): readonly AgentToolContract[] {
+    return this.workflowTools.list();
+  }
+
+  private validate(document: unknown): ProcessIssue[] {
+    return validateProcess(document, { tools: (name) => this.workflowTools.has(name) });
+  }
+
+  private async process(key: string, tracked: boolean): Promise<WfProcess> {
+    const source = tracked ? this.db.processes : this.db.processes.asNoTracking();
+    const row = await source.firstOrDefault((p) => p.key.eq(key));
+    if (!row) throw notFound(key);
+    return row;
+  }
+}
+
+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");
+  return value;
+}
+
+function description(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");
+  return value;
+}
+
+function retention(value: unknown): number | null {
+  if (value === undefined || value === null) return null;
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > 36_500) throw new WorkflowError("invalid_input", "retentionDays must be an integer 1–36500");
+  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,
+    key,
+    version: row.version,
+    publishedAt: row.publishedAt,
+    publishedBy: { kind: row.publishedByKind === "system" ? "system" : "user", id: row.publishedById },
+    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/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Business processes without a UI (WORKFLOW-001): the composite `WorkflowModule`
+ * with the Definitions and Runtime parts, their services, HTTP, events and
+ * extension points. The document format is `bazis/library/workflow`.
+ */
+export { WorkflowModule } from "./Workflow.module";
+export { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefinitions.module";
+export { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
+export {
+  IWorkflowDefinitions,
+  type CreateProcess,
+  type ProcessDetails,
+  type ProcessListQuery,
+  type ProcessSummary,
+  type UpdateProcess,
+  type VersionDetails,
+  type VersionSummary,
+} from "./definitions_module/services/IWorkflowDefinitions.service";
+export {
+  IWorkflowRuntime,
+  type HistoryEntry,
+  type InstanceDetails,
+  type InstanceListQuery,
+  type InstanceSummary,
+  type StartInstance,
+  type TokenDetails,
+} from "./runtime_module/services/IWorkflowRuntime.service";
+export {
+  WORKFLOW_INSTANCE_FINISHED,
+  WORKFLOW_TASK_REQUESTED,
+  WORKFLOW_TOKEN_CLOSED,
+  type WorkflowInstanceFinished,
+  type WorkflowTaskRequested,
+  type WorkflowTokenClosed,
+} from "./runtime_module/events/Runtime.events";
+export { workflowRuntimeConfig } from "./runtime_module/config/Runtime.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 { WorkflowAccess, DenyWorkflowAccess, type WorkflowAccessTarget, type WorkflowAction } from "./access/WorkflowAccess";
+export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
+export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
+export type { WorkflowActor, WorkflowPage, WorkflowPaging } from "./contracts/types";

package/core/workflow/internal/WorkflowTools.ts

@@ -0,0 +1,36 @@
+import type { ServiceResolver } from "../../di";
+import { ToolRunner, type AgentToolContract, type BoundToolRunner } from "../../agent";
+
+/** The workflow caller id of TOOLS-001: processes run only Tools whose `callers` list it. */
+export const WORKFLOW_CALLER = "workflow";
+
+/**
+ * The application's Tools as processes see them. `ToolRunner` exists only when
+ * a module declares `tools`; without it there is nothing to call.
+ */
+export class WorkflowTools {
+  private readonly runner: BoundToolRunner | undefined;
+
+  constructor(services: ServiceResolver) {
+    this.runner = services.tryResolve(ToolRunner)?.as(WORKFLOW_CALLER);
+  }
+
+  /** Whether a service task may call `name`. */
+  has(name: string): boolean {
+    return this.runner?.getTool(name) !== undefined;
+  }
+
+  /** Contracts of every Tool processes may call, by name. */
+  list(): readonly AgentToolContract[] {
+    if (this.runner === undefined) return [];
+    return this.runner.listTools()
+      .map((tool) => this.runner!.describe(tool.metadata.name))
+      .filter((contract): contract is AgentToolContract => contract !== undefined)
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /** The bound runner; `undefined` when the application has no Tools. */
+  get bound(): BoundToolRunner | undefined {
+    return this.runner;
+  }
+}

package/core/workflow/internal/http.ts

@@ -0,0 +1,63 @@
+import { ForbiddenError, UnauthorizedError, type HttpContext } from "../../http";
+import { WorkflowAccess, type WorkflowAccessTarget, type WorkflowAction } from "../access/WorkflowAccess";
+import type { WorkflowActor } from "../contracts/types";
+import { WorkflowError } from "../contracts/WorkflowError";
+
+/**
+ * Asks the application's {@link WorkflowAccess} who calls and whether the action
+ * is allowed. Without a registered access every route answers 403.
+ */
+export async function authorize(ctx: HttpContext, action: WorkflowAction, target: WorkflowAccessTarget = {}): Promise<WorkflowActor> {
+  const access = ctx.services.tryResolve(WorkflowAccess);
+  if (access === undefined) throw new ForbiddenError("Workflow HTTP is closed: register a WorkflowAccess implementation");
+  const actor = await access.actor(ctx);
+  if (actor === undefined) throw new UnauthorizedError();
+  if (!await access.can(ctx, action, target)) throw new ForbiddenError();
+  return actor;
+}
+
+/** A route parameter as a string. */
+export function param(ctx: HttpContext, name: string): string {
+  return String(ctx.params[name] ?? "");
+}
+
+/** 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();
+  if (text.trim() === "") return {};
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new WorkflowError("invalid_input", "The body must be JSON");
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new WorkflowError("invalid_input", "The body must be a JSON object");
+  return value as Record<string, unknown>;
+}
+
+/** An optional string field of a body or a query; another type is `invalid_input`. */
+export function optionalString(value: unknown, name: string, max = 200): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length > max) throw new WorkflowError("invalid_input", `${name} must be a string up to ${max} characters`);
+  return value;
+}
+
+/** A required string field. */
+export function requiredString(value: unknown, name: string, max = 200): string {
+  const text = optionalString(value, name, max);
+  if (text === undefined || text.trim() === "") throw new WorkflowError("invalid_input", `${name} is required`);
+  return text;
+}
+
+/** An optional integer from a query string or a body. */
+export function optionalInteger(value: unknown, name: string): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const number = typeof value === "string" ? Number(value) : value;
+  if (!Number.isSafeInteger(number)) throw new WorkflowError("invalid_input", `${name} must be an integer`);
+  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") };
+}

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

@@ -0,0 +1,53 @@
+import { DI, Module, SERVICE_PROVIDER, scoped } from "../../di";
+import { EventBus, LOGGER } from "../../kernel";
+import { DefaultWorkflowInputValidator, WorkflowInputValidator } from "../contracts/WorkflowInputValidator";
+import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
+import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
+import { WorkflowTools } from "../internal/WorkflowTools";
+import { WorkflowRetention } from "./background/WorkflowRetention";
+import { WorkflowWorker } from "./background/WorkflowWorker";
+import { workflowRuntimeConfig } from "./config/Runtime.config";
+import { InstancesController } from "./http/Instances.controller";
+import { GraphCache } from "./internal/GraphCache";
+import { ToolStep } from "./internal/ToolStep";
+import { WorkflowEngine } from "./internal/WorkflowEngine";
+import { RUNTIME_ENTITIES, RuntimeDbContext, runtimeStore } from "./model/Runtime.dbContext";
+import { IWorkflowRuntime } from "./services/IWorkflowRuntime.service";
+import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
+
+/**
+ * Runs published versions: instances, tokens, jobs, history, the worker and
+ * retention ([passport](MODULE.md)). Dependencies are explicit: the framework's
+ * classes are not covered by the application's codegen.
+ */
+@Module({
+  imports: [WorkflowDefinitionsModule],
+  config: [workflowRuntimeConfig],
+  ormBazis: { context: RuntimeDbContext, entities: [...RUNTIME_ENTITIES], ownedStore: runtimeStore, registerRepositories: false },
+  providers: [
+    DI.singleton(DI.factoryProvider(GraphCache, [], () => new GraphCache())),
+    DI.scoped(DI.factoryProviderWithResolver(WorkflowEngine, [], (resolver) => new WorkflowEngine(
+      resolver.resolve(RuntimeDbContext),
+      resolver.resolve(IWorkflowDefinitions),
+      resolver.resolve(GraphCache),
+      resolver.resolve(EventBus),
+      resolver,
+      resolver.tryResolve(LOGGER),
+    ))),
+    scoped(ToolStep, ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools] as const),
+    // The application's input validator, if it registered one anywhere; the built-in one otherwise.
+    DI.scoped(DI.factoryProviderWithResolver(IWorkflowRuntime, [], (resolver) => new WorkflowRuntime(
+      resolver.resolve(RuntimeDbContext),
+      resolver.resolve(WorkflowEngine),
+      resolver.resolve(IWorkflowDefinitions),
+      resolver.resolve(SERVICE_PROVIDER).tryResolve(WorkflowInputValidator) ?? new DefaultWorkflowInputValidator(),
+    ))),
+  ],
+  controllers: [DI.bindDeps(InstancesController, IWorkflowRuntime)],
+  background: [
+    DI.bindDeps(WorkflowWorker, SERVICE_PROVIDER, workflowRuntimeConfig.token),
+    DI.bindDeps(WorkflowRetention, SERVICE_PROVIDER, workflowRuntimeConfig.token),
+  ],
+  exports: [IWorkflowRuntime],
+})
+export class WorkflowRuntimeModule {}

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

@@ -0,0 +1,66 @@
+import { BackgroundService, delay } from "../../../background";
+import type { ServiceProvider } from "../../../di";
+import type { ConfigView } from "../../../kernel";
+import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WorkflowSettings } from "./WorkflowWorker";
+
+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.
+ */
+export class WorkflowRetention extends BackgroundService {
+  constructor(
+    private readonly services: ServiceProvider,
+    private readonly config: ConfigView<WorkflowSettings>,
+  ) {
+    super();
+  }
+
+  protected override async execute(signal: AbortSignal): Promise<void> {
+    if (!this.config.get("retention.enabled")) return;
+    const intervalMs = this.config.get("retention.intervalMs");
+    while (!signal.aborted) {
+      try {
+        await this.sweep(signal);
+      } catch (error) {
+        if (signal.aborted) return;
+        this.reportFailure("retention sweep failed", error);
+      }
+      await delay(intervalMs, signal);
+    }
+  }
+
+  /** One pass over every process with a retention period; returns how many instances went. */
+  async sweep(signal?: AbortSignal): Promise<number> {
+    const batchSize = this.config.get("retention.batchSize");
+    const scope = this.services.createScope();
+    let deleted = 0;
+    try {
+      const definitions = scope.resolve(IWorkflowDefinitions);
+      const db = scope.resolve(RuntimeDbContext);
+      for (const policy of await definitions.retentionPolicies()) {
+        const cutoff = new Date(Date.now() - policy.retentionDays * DAY_MS);
+        for (;;) {
+          if (signal?.aborted) return deleted;
+          const ids = (await db.instances.asNoTracking()
+            .where((i) => i.processKey.eq(policy.key).and(i.status.in(["completed", "cancelled"])).and(i.endedAt.lt(cutoff)))
+            .orderBy((i) => i.id)
+            .take(batchSize)
+            .select((i) => ({ id: i.id }))
+            .toList()).map((row) => row.id);
+          if (ids.length === 0) break;
+          await db.instances.asNoTracking().where((i) => i.id.in(ids)).executeDelete();
+          deleted += ids.length;
+          if (ids.length < batchSize) break;
+        }
+      }
+    } finally {
+      await scope.dispose();
+    }
+    return deleted;
+  }
+}

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

@@ -0,0 +1,92 @@
+import { BackgroundService, delay } from "../../../background";
+import type { ServiceProvider } from "../../../di";
+import type { ConfigView } from "../../../kernel";
+import type { workflowRuntimeConfig } from "../config/Runtime.config";
+import { ToolStep } from "../internal/ToolStep";
+import { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfJob } from "../model/WfJob.model";
+
+/** How long a claimed job belongs to this worker; if it dies, another one takes the job after that. */
+const LEASE_MS = 5 * 60_000;
+
+
+/**
+ * Takes due jobs of `bazis_wf_run_jobs` every `worker.intervalMs`, up to
+ * `worker.batchSize` at a time, with `FOR UPDATE SKIP LOCKED` and a lease, so
+ * application instances never take one job twice. A full batch is followed by
+ * the next one at once. Every job runs in its own DI scope.
+ */
+export class WorkflowWorker extends BackgroundService {
+  constructor(
+    private readonly services: ServiceProvider,
+    private readonly config: ConfigView<WorkflowSettings>,
+  ) {
+    super();
+  }
+
+  protected override async execute(signal: AbortSignal): Promise<void> {
+    if (!this.config.get("worker.enabled")) return;
+    const intervalMs = this.config.get("worker.intervalMs");
+    const batchSize = this.config.get("worker.batchSize");
+    while (!signal.aborted) {
+      let claimed = 0;
+      try {
+        const jobs = await this.claim(batchSize);
+        claimed = jobs.length;
+        for (const job of jobs) {
+          if (signal.aborted) return;
+          await this.run(job, signal);
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        this.reportFailure("claiming jobs failed", error);
+      }
+      if (claimed < batchSize) await delay(intervalMs, signal);
+    }
+  }
+
+  private async run(job: WfJob, signal: AbortSignal): Promise<void> {
+    const scope = this.services.createScope();
+    try {
+      await scope.resolve(ToolStep).run(job, signal);
+    } catch (error) {
+      this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId });
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  private async claim(batchSize: number): Promise<WfJob[]> {
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      return await db.transactionScope(async () => {
+        const now = new Date();
+        const jobs = await db.jobs
+          .where((j) => j.kind.eq("tool").and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
+          .orderBy((j) => j.id)
+          .take(batchSize)
+          .forUpdate({ skipLocked: true })
+          .toList();
+        for (const job of jobs) {
+          job.lockedUntil = new Date(now.getTime() + LEASE_MS);
+          job.attempts += 1;
+        }
+        await db.saveChanges();
+        return jobs;
+      });
+    } finally {
+      await scope.dispose();
+    }
+  }
+}
+
+/** The resolved settings of {@link workflowRuntimeConfig}. */
+export interface WorkflowSettings {
+  readonly "worker.enabled": boolean;
+  readonly "worker.intervalMs": number;
+  readonly "worker.batchSize": number;
+  readonly "retention.enabled": boolean;
+  readonly "retention.intervalMs": number;
+  readonly "retention.batchSize": number;
+}

package/core/workflow/runtime_module/config/Runtime.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "../../../kernel";
+
+/**
+ * Settings of the workflow background services (WORKFLOW-001 §4), from the
+ * application configuration: `BAZIS_WORKFLOW__WORKER__ENABLED=false` keeps an
+ * instance from running jobs, for example a web-only one.
+ */
+export const workflowRuntimeConfig = defineConfig("workflow", {
+  default: {
+    "worker.enabled": true,
+    "worker.intervalMs": 1000,
+    "worker.batchSize": 10,
+    "retention.enabled": true,
+    "retention.intervalMs": 3_600_000,
+    "retention.batchSize": 500,
+  },
+  validate: {
+    "worker.intervalMs": (value) => positive(value, 3_600_000),
+    "worker.batchSize": (value) => positive(value, 1000),
+    "retention.intervalMs": (value) => positive(value, 86_400_000),
+    "retention.batchSize": (value) => positive(value, 10_000),
+  },
+});
+
+function positive(value: unknown, max: number): string | undefined {
+  return Number.isSafeInteger(value) && (value as number) >= 1 && (value as number) <= max ? undefined : `must be an integer 1–${max}`;
+}

package/core/workflow/runtime_module/events/Runtime.events.ts

@@ -0,0 +1,36 @@
+import { createEventToken } from "../../../kernel";
+import type { FormSpec } from "../../../../library/workflow";
+import type { InstanceStatus } from "../model/WfInstance.model";
+
+/** A token reached a user task. Published after the step commits. */
+export interface WorkflowTaskRequested {
+  readonly instanceId: string;
+  readonly tokenId: string;
+  readonly processKey: string;
+  readonly nodeId: string;
+  readonly partition: string | null;
+  readonly title: string;
+  readonly assignee: { readonly role: string } | { readonly user: string };
+  readonly form: FormSpec | null;
+  /** When the task is due, from the node's `dueIn`. */
+  readonly dueAt: Date | null;
+}
+
+/** A waiting token was closed otherwise than by its task: the task is dropped. */
+export interface WorkflowTokenClosed {
+  readonly instanceId: string;
+  readonly tokenId: string;
+  readonly reason: "cancelled";
+}
+
+/** An instance finished: completed or cancelled. */
+export interface WorkflowInstanceFinished {
+  readonly instanceId: string;
+  readonly processKey: string;
+  readonly partition: string | null;
+  readonly status: Extract<InstanceStatus, "completed" | "cancelled">;
+}
+
+export const WORKFLOW_TASK_REQUESTED = createEventToken<WorkflowTaskRequested>("workflow.task-requested");
+export const WORKFLOW_TOKEN_CLOSED = createEventToken<WorkflowTokenClosed>("workflow.token-closed");
+export const WORKFLOW_INSTANCE_FINISHED = createEventToken<WorkflowInstanceFinished>("workflow.instance-finished");