bazis 0.126.0 → 0.128.0

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

@@ -1,53 +1,46 @@
 import { BackgroundService, delay } from "../../../background";
 import type { ServiceProvider } from "../../../di";
+import { WorkflowClock } from "../../contracts/WorkflowClock";
 import type { ConfigView } from "../../../kernel";
 import type { workflowRuntimeConfig } from "../config/Runtime.config";
-import { Schedules } from "../internal/Schedules";
-import { TimerStep } from "../internal/TimerStep";
-import { ToolStep } from "../internal/ToolStep";
-import { WorkflowEngine } from "../internal/WorkflowEngine";
-import { RuntimeDbContext } from "../model/Runtime.dbContext";
-import type { WfJob } from "../model/WfJob.model";
+import { WorkflowJobs } from "../internal/WorkflowJobs";
 
-/** 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;
-/** A job that keeps failing outside its Tool (the database, a lost version) fails its step after this many tries. */
-const MAX_JOB_ATTEMPTS = 5;
 /** How often the scheduled starts are matched against the published versions. */
 const RECONCILE_MS = 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.
+ * `worker.batchSize` at a time ({@link WorkflowJobs}). A full batch is
+ * followed by the next one at once.
  */
 export class WorkflowWorker extends BackgroundService {
+  private readonly jobs: WorkflowJobs;
+
   constructor(
     private readonly services: ServiceProvider,
     private readonly config: ConfigView<WorkflowSettings>,
   ) {
     super();
+    this.jobs = new WorkflowJobs(services, (message, error, fields) => this.reportFailure(message, error, fields));
   }
 
   protected override async execute(signal: AbortSignal): Promise<void> {
-    if (!this.config.get("worker.enabled")) return;
+    if (!this.config.get("worker.enabled") || this.services.resolve(WorkflowClock).manual === true) return;
     const intervalMs = this.config.get("worker.intervalMs");
     const batchSize = this.config.get("worker.batchSize");
     let reconciledAt = 0;
     while (!signal.aborted) {
       if (Date.now() - reconciledAt >= RECONCILE_MS) {
         reconciledAt = Date.now();
-        await this.reconcile();
+        await this.jobs.reconcile();
       }
       let claimed = 0;
       try {
-        const jobs = await this.claim(batchSize);
+        const jobs = await this.jobs.claim(batchSize);
         claimed = jobs.length;
         for (const job of jobs) {
           if (signal.aborted) return;
-          await this.run(job, signal);
+          await this.jobs.run(job, signal);
         }
       } catch (error) {
         if (signal.aborted) return;
@@ -56,76 +49,6 @@ export class WorkflowWorker extends BackgroundService {
       if (claimed < batchSize) await delay(intervalMs, signal);
     }
   }
-
-  private async run(job: WfJob, signal: AbortSignal): Promise<void> {
-    const scope = this.services.createScope();
-    try {
-      if (job.kind === "timer") await scope.resolve(TimerStep).run(job);
-      else if (job.kind === "schedule") await scope.resolve(Schedules).fire(job);
-      else await scope.resolve(ToolStep).run(job, signal);
-    } catch (error) {
-      this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId, attempts: job.attempts });
-      await this.giveUpOrDelay(job, error).catch((failure: unknown) => this.reportFailure("job failure handling failed", failure, { job: job.id }));
-    } finally {
-      await scope.dispose();
-    }
-  }
-
-  private async reconcile(): Promise<void> {
-    const scope = this.services.createScope();
-    try {
-      await scope.resolve(Schedules).reconcile();
-    } catch (error) {
-      this.reportFailure("scheduled starts could not be planned", error);
-    } finally {
-      await scope.dispose();
-    }
-  }
-
-  /** A job that failed outside its Tool waits a minute per try, then fails its step for a person to retry. */
-  private async giveUpOrDelay(job: WfJob, error: unknown): Promise<void> {
-    const message = error instanceof Error ? error.message : String(error);
-    const scope = this.services.createScope();
-    try {
-      const db = scope.resolve(RuntimeDbContext);
-      if (job.attempts < MAX_JOB_ATTEMPTS || job.instanceId === null || job.tokenId === null) {
-        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: new Date(Date.now() + job.attempts * 60_000), lockedUntil: null, lastError: message.slice(0, 1000) });
-        return;
-      }
-      const engine = scope.resolve(WorkflowEngine);
-      await engine.inStep(job.instanceId, async (step) => {
-        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
-        const token = step.tokens.find((t) => t.id === job.tokenId);
-        if (token && token.status === "waiting" && step.instance.status === "running") engine.fail(step, token, "job_failed", message.slice(0, 1000));
-      });
-    } 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.in(["tool", "timer", "schedule"]).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}. */

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

@@ -32,6 +32,12 @@ export interface WorkflowInstanceFinished {
   readonly status: Extract<InstanceStatus, "completed" | "cancelled">;
 }
 
+/** Retention deleted these finished instances with their tokens and history. */
+export interface WorkflowInstancesDeleted {
+  readonly instanceIds: readonly string[];
+}
+
 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");
+export const WORKFLOW_INSTANCES_DELETED = createEventToken<WorkflowInstancesDeleted>("workflow.instances-deleted");

package/core/workflow/runtime_module/internal/Schedules.ts

@@ -22,7 +22,7 @@ export class Schedules {
   ) {}
 
   /** Adds jobs for new scheduled versions and drops those of replaced or archived ones. */
-  async reconcile(now = new Date()): Promise<void> {
+  async reconcile(now = this.engine.now()): Promise<void> {
     const versions = (await this.definitions.published()).filter((version) => scheduleNodes(version).length > 0);
     const wanted = new Map(versions.map((version) => [version.id, version]));
     const added: WfJob[] = [];
@@ -58,7 +58,9 @@ export class Schedules {
     const due = new Date(Math.floor(job.dueAt.getTime() / 60_000) * 60_000);
     const graph = this.engine.cache(latest);
     await this.db.transactionScope(async () => {
-      const next = nextFiring(latest, due);
+      // Planned from now, not from the missed firing: a stopped worker does not catch up.
+      const now = this.engine.now();
+      const next = nextFiring(latest, now > due ? now : due);
       if (next === undefined) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       else await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: next, lockedUntil: null, attempts: 0, lastError: null });
       for (const [nodeId, cron] of scheduleNodes(latest)) {

package/core/workflow/runtime_module/internal/ToolStep.ts

@@ -44,7 +44,7 @@ export class ToolStep {
     await this.engine.inStep(instance.id, async (step) => {
       const current = step.tokens.find((t) => t.id === token.id);
       const retryAt = current?.status === "waiting" && step.instance.status === "running" && result.status === "error" && reason === undefined
-        ? nextAttempt(node?.config?.retry, job.attempts)
+        ? nextAttempt(node?.config?.retry, job.attempts, this.engine.now())
         : undefined;
       if (retryAt !== undefined) {
         // The same job runs again later: its attempts keep counting.
@@ -87,10 +87,10 @@ function reasonOf(result: AgentToolResult): string | undefined {
  * `undefined` when the attempts are used up. The pause doubles from `backoff`
  * (10 seconds by default) and stops growing at a day.
  */
-export function nextAttempt(policy: unknown, attempts: number): Date | undefined {
+export function nextAttempt(policy: unknown, attempts: number, now: Date): Date | undefined {
   if (typeof policy !== "object" || policy === null) return undefined;
   const { maxAttempts, backoff } = policy as { maxAttempts?: unknown; backoff?: unknown };
   if (typeof maxAttempts !== "number" || attempts >= maxAttempts) return undefined;
   const base = typeof backoff === "string" ? durationMs(backoff) ?? 10_000 : 10_000;
-  return new Date(Date.now() + Math.min(base * 2 ** Math.max(attempts - 1, 0), 86_400_000));
+  return new Date(now.getTime() + Math.min(base * 2 ** Math.max(attempts - 1, 0), 86_400_000));
 }

package/core/workflow/runtime_module/internal/WorkflowEngine.ts

@@ -2,6 +2,7 @@ import type { ServiceResolver } from "../../../di";
 import { EventBus, type EventToken, type Logger } from "../../../kernel";
 import { durationMs, evaluateCondition, nodeKindOf, readPath, type FormSpec, type InstanceData, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
 import type { WorkflowActor } from "../../contracts/types";
+import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import { WORKFLOW_INSTANCE_FINISHED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED } from "../events/Runtime.events";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
@@ -53,8 +54,14 @@ export class WorkflowEngine {
     private readonly events: EventBus,
     private readonly scope: ServiceResolver,
     private readonly logger: Logger | undefined,
+    private readonly clock: WorkflowClock,
   ) {}
 
+  /** The engine's time ({@link WorkflowClock}). */
+  now(): Date {
+    return this.clock.now();
+  }
+
   /** The graph of a version. Versions are immutable, so graphs are cached. */
   async graphOf(versionId: string): Promise<ProcessGraph> {
     const cached = this.graphs.get(versionId);
@@ -168,7 +175,7 @@ export class WorkflowEngine {
     const token = step.tokens.find((t) => t.id === tokenId);
     if (!token || token.status !== "waiting" || step.instance.status !== "running") return false;
     const node = step.graph.document.nodes[token.nodeId];
-    const firedAt = new Date().toISOString();
+    const firedAt = this.now().toISOString();
     if (node?.kind === "timerCatch") {
       this.history(step, token, token.nodeId, "timer", { firedAt });
       return await this.complete(step, tokenId, { firedAt });
@@ -239,12 +246,12 @@ export class WorkflowEngine {
     const open = step.tokens.filter((t) => LIVE.has(t.status));
     for (const token of open) {
       token.status = "cancelled";
-      token.endedAt = new Date();
+      token.endedAt = this.now();
     }
     await this.db.jobs.asNoTracking().where((j) => j.instanceId.eq(step.instance.id)).executeDelete();
     await this.db.subscriptions.asNoTracking().where((s) => s.instanceId.eq(step.instance.id)).executeDelete();
     step.instance.status = "cancelled";
-    step.instance.endedAt = new Date();
+    step.instance.endedAt = this.now();
     this.history(step, null, null, "cancelled", { reason }, actor);
     for (const token of open) {
       if (token.nodeId !== "" && step.graph.document.nodes[token.nodeId]?.kind === "userTask") {
@@ -278,7 +285,7 @@ export class WorkflowEngine {
     }
     if (step.instance.status === "running" && !step.tokens.some((t) => LIVE.has(t.status))) {
       step.instance.status = "completed";
-      step.instance.endedAt = new Date();
+      step.instance.endedAt = this.now();
       this.history(step, null, null, "completed", null);
       this.finished(step, "completed");
     }
@@ -319,7 +326,7 @@ export class WorkflowEngine {
   }
 
   private waitForTimer(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
-    const dueAt = timerDue(node.config ?? {}, dataOf(step.instance));
+    const dueAt = timerDue(node.config ?? {}, dataOf(step.instance), this.now());
     if (dueAt === undefined) {
       this.fail(step, token, "bad_timer", `the timer of ${token.nodeId} has no valid date`);
       return [];
@@ -348,7 +355,7 @@ export class WorkflowEngine {
         continue;
       }
       if (node.kind !== "boundaryTimer") continue;
-      const dueAt = timerDue(node.config ?? {}, dataOf(step.instance));
+      const dueAt = timerDue(node.config ?? {}, dataOf(step.instance), this.now());
       if (dueAt === undefined) {
         this.fail(step, host, "bad_timer", `the timer of ${id} has no valid date`);
         return [];
@@ -393,7 +400,7 @@ export class WorkflowEngine {
 
   private waitForTool(step: Step, token: WfToken): WfToken[] {
     token.status = "waiting";
-    this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "tool" as const, instanceId: step.instance.id, tokenId: token.id, dueAt: new Date() }));
+    this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "tool" as const, instanceId: step.instance.id, tokenId: token.id, dueAt: this.now() }));
     return [];
   }
 
@@ -412,7 +419,7 @@ export class WorkflowEngine {
         title: node.title,
         assignee: config.assignee as { role: string } | { user: string },
         form: (config.form as FormSpec | undefined) ?? null,
-        dueAt: dueIn === undefined ? null : new Date(Date.now() + dueIn),
+        dueAt: dueIn === undefined ? null : new Date(this.now().getTime() + dueIn),
       },
     });
     return [];
@@ -467,7 +474,7 @@ export class WorkflowEngine {
 
   private close(token: WfToken, status: "done" | "cancelled"): void {
     token.status = status;
-    token.endedAt = new Date();
+    token.endedAt = this.now();
   }
 
   private spawn(step: Step, nodeId: string, viaFlowId: string | null): WfToken {
@@ -505,10 +512,10 @@ export class WorkflowEngine {
 }
 
 /** When a timer fires: `duration` from now, or the date at the `at` path; `undefined` if neither is valid. */
-export function timerDue(config: Readonly<Record<string, unknown>>, data: InstanceData): Date | undefined {
+export function timerDue(config: Readonly<Record<string, unknown>>, data: InstanceData, now: Date): Date | undefined {
   if (typeof config.duration === "string") {
     const ms = durationMs(config.duration);
-    return ms === undefined ? undefined : new Date(Date.now() + ms);
+    return ms === undefined ? undefined : new Date(now.getTime() + ms);
   }
   if (typeof config.at === "string") {
     const value = readPath(data, config.at);

package/core/workflow/runtime_module/internal/WorkflowJobs.ts

@@ -0,0 +1,100 @@
+import type { ServiceProvider } from "../../../di";
+import { WorkflowClock } from "../../contracts/WorkflowClock";
+import { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfJob } from "../model/WfJob.model";
+import { Schedules } from "./Schedules";
+import { TimerStep } from "./TimerStep";
+import { ToolStep } from "./ToolStep";
+import { WorkflowEngine } from "./WorkflowEngine";
+
+/** How long a claimed job belongs to its worker; if it dies, another one takes the job after that. */
+const LEASE_MS = 5 * 60_000;
+/** A job that keeps failing outside its Tool (the database, a lost version) fails its step after this many tries. */
+const MAX_JOB_ATTEMPTS = 5;
+
+/** Where a failure goes: the worker's log. */
+export type JobFailureReport = (message: string, error: unknown, fields?: Readonly<Record<string, unknown>>) => void;
+
+/**
+ * Claiming and running jobs of `bazis_wf_run_jobs`: the work of the worker, and
+ * of `drain` in tests. Every job runs in its own DI scope.
+ */
+export class WorkflowJobs {
+  constructor(
+    private readonly services: ServiceProvider,
+    private readonly report: JobFailureReport,
+  ) {}
+
+  /** Takes up to `batchSize` due jobs with `FOR UPDATE SKIP LOCKED` and a lease, so instances never take one job twice. */
+  async claim(batchSize: number): Promise<WfJob[]> {
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      const now = scope.resolve(WorkflowClock).now();
+      return await db.transactionScope(async () => {
+        const jobs = await db.jobs
+          .where((j) => j.kind.in(["tool", "timer", "schedule"]).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();
+    }
+  }
+
+  async run(job: WfJob, signal: AbortSignal): Promise<void> {
+    const scope = this.services.createScope();
+    try {
+      if (job.kind === "timer") await scope.resolve(TimerStep).run(job);
+      else if (job.kind === "schedule") await scope.resolve(Schedules).fire(job);
+      else await scope.resolve(ToolStep).run(job, signal);
+    } catch (error) {
+      this.report("job failed", error, { job: job.id, instance: job.instanceId, attempts: job.attempts });
+      await this.giveUpOrDelay(job, error).catch((failure: unknown) => this.report("job failure handling failed", failure, { job: job.id }));
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  /** Matches the scheduled starts against the published versions. */
+  async reconcile(): Promise<void> {
+    const scope = this.services.createScope();
+    try {
+      await scope.resolve(Schedules).reconcile();
+    } catch (error) {
+      this.report("scheduled starts could not be planned", error);
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  /** A job that failed outside its Tool waits a minute per try, then fails its step for a person to retry. */
+  private async giveUpOrDelay(job: WfJob, error: unknown): Promise<void> {
+    const message = error instanceof Error ? error.message : String(error);
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      if (job.attempts < MAX_JOB_ATTEMPTS || job.instanceId === null || job.tokenId === null) {
+        const now = scope.resolve(WorkflowClock).now();
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: new Date(now.getTime() + job.attempts * 60_000), lockedUntil: null, lastError: message.slice(0, 1000) });
+        return;
+      }
+      const engine = scope.resolve(WorkflowEngine);
+      await engine.inStep(job.instanceId, async (step) => {
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+        const token = step.tokens.find((t) => t.id === job.tokenId);
+        if (token && token.status === "waiting" && step.instance.status === "running") engine.fail(step, token, "job_failed", message.slice(0, 1000));
+      });
+    } finally {
+      await scope.dispose();
+    }
+  }
+}

package/core/workflow/tasks_module/WorkflowTasks.module.ts

@@ -0,0 +1,31 @@
+import { DI, Module, scoped } from "../../di";
+import { WorkflowClock } from "../contracts/WorkflowClock";
+import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
+import { withEventSubscribers } from "../../kernel";
+import { IWorkflowRuntime } from "../runtime_module/services/IWorkflowRuntime.service";
+import { WorkflowRuntimeModule } from "../runtime_module/WorkflowRuntime.module";
+import { TaskEvents } from "./events/TaskEvents";
+import { TasksController } from "./http/Tasks.controller";
+import { TasksDbContext, tasksStore } from "./model/Tasks.dbContext";
+import { WfTask } from "./model/WfTask.model";
+import { IWorkflowTasks } from "./services/IWorkflowTasks.service";
+import { WorkflowTasks } from "./services/WorkflowTasks.service";
+
+/**
+ * Tasks for people: the inbox of `userTask` steps ([passport](MODULE.md)).
+ * Dependencies are explicit: the framework's classes are not covered by the
+ * application's codegen.
+ */
+@Module({
+  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule],
+  ormBazis: { context: TasksDbContext, entities: [WfTask], ownedStore: tasksStore, registerRepositories: false },
+  providers: [
+    scoped(WorkflowTasks, WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock] as const),
+    DI.scoped(DI.factoryProviderWithResolver(IWorkflowTasks, [], (resolver) => resolver.resolve(WorkflowTasks))),
+    scoped(TaskEvents, TaskEvents, [WorkflowTasks] as const),
+    ...withEventSubscribers(TaskEvents),
+  ],
+  controllers: [DI.bindDeps(TasksController, IWorkflowTasks)],
+  exports: [IWorkflowTasks],
+})
+export class WorkflowTasksModule {}

package/core/workflow/tasks_module/events/TaskEvents.ts

@@ -0,0 +1,23 @@
+import { OnEvent } from "../../../kernel";
+import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
+import type { WorkflowTasks } from "../services/WorkflowTasks.service";
+
+/** Keeps the inbox in line with the steps: a waiting user task gets a task, a closed one cancels it. */
+export class TaskEvents {
+  constructor(private readonly tasks: WorkflowTasks) {}
+
+  @OnEvent(WORKFLOW_TASK_REQUESTED)
+  requested(event: WorkflowTaskRequested): Promise<void> {
+    return this.tasks.requested(event);
+  }
+
+  @OnEvent(WORKFLOW_TOKEN_CLOSED)
+  closed(event: WorkflowTokenClosed): Promise<void> {
+    return this.tasks.closed(event);
+  }
+
+  @OnEvent(WORKFLOW_INSTANCES_DELETED)
+  deleted(event: WorkflowInstancesDeleted): Promise<void> {
+    return this.tasks.deleted(event);
+  }
+}

package/core/workflow/tasks_module/http/Tasks.controller.ts

@@ -0,0 +1,67 @@
+import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
+import { Controller, Get, Post, type HttpContext } from "../../../http";
+import type { WorkflowActor } from "../../contracts/types";
+import { WorkflowError } from "../../contracts/WorkflowError";
+import { assigneesOf, authorize, body, optionalString, pagingQuery, param } from "../../internal/http";
+import type { TaskStatus } from "../model/WfTask.model";
+import { IWorkflowTasks, type TaskDetails } from "../services/IWorkflowTasks.service";
+
+/**
+ * The caller's tasks (WORKFLOW-001 §5): those addressed to any of
+ * `WorkflowAccess.assignees` or claimed by the caller. Another person's task
+ * answers 404, as if it did not exist.
+ */
+@Controller("workflow/tasks")
+export class TasksController {
+  constructor(private readonly tasks: IWorkflowTasks) {}
+
+  @Get()
+  async list(ctx: HttpContext) {
+    const partition = optionalString(ctx.query("partition"), "partition");
+    const actor = await authorize(ctx, "tasks.work", { partition: partition ?? null });
+    const status = ctx.query("status");
+    const page = await this.tasks.list({
+      ...pagingQuery(ctx),
+      assignees: await assigneesOf(ctx, actor),
+      actor,
+      ...(status === undefined ? {} : { status: status.split(",") as TaskStatus[] }),
+      partition,
+      processKey: optionalString(ctx.query("processKey"), "processKey"),
+    });
+    return { data: page.items, meta: { total: page.total } };
+  }
+
+  @Get(":id")
+  async get(ctx: HttpContext) {
+    return (await this.visible(ctx)).task;
+  }
+
+  @Post(":id/claim")
+  async claim(ctx: HttpContext) {
+    const { task, actor } = await this.visible(ctx);
+    return await this.tasks.claim(task.id, actor);
+  }
+
+  @Post(":id/release")
+  async release(ctx: HttpContext) {
+    const { task, actor } = await this.visible(ctx);
+    return await this.tasks.release(task.id, actor);
+  }
+
+  @Post(":id/complete")
+  async complete(ctx: HttpContext) {
+    const { task, actor } = await this.visible(ctx);
+    const request = await body(ctx);
+    return await this.tasks.complete(task.id, request.output ?? {}, actor);
+  }
+
+  /** The task if the caller may see it: addressed to one of their assignees or claimed by them. */
+  private async visible(ctx: HttpContext): Promise<{ task: TaskDetails; actor: WorkflowActor }> {
+    const task = await this.tasks.get(param(ctx, "id"));
+    const actor = await authorize(ctx, "tasks.work", { processKey: task.processKey, partition: task.partition, instanceId: task.instanceId, taskId: task.id });
+    const assignees = await assigneesOf(ctx, actor);
+    if (!assignees.includes(task.assignee) && task.claimedBy !== actor.id) throw new WorkflowError("not_found", `Task ${task.id} does not exist`);
+    return { task, actor };
+  }
+}
+contextOnlyController(TasksController);

package/core/workflow/tasks_module/model/Tasks.dbContext.ts

@@ -0,0 +1,14 @@
+import { DbContext, defineOrmOwnedStoreV1 } from "../../../orm";
+import { WfTask } from "./WfTask.model";
+
+export class TasksDbContext extends DbContext {
+  readonly tasks = this.set(WfTask);
+}
+
+/** The table of the Tasks part: bazis creates and checks it in the application database. */
+export const tasksStore = defineOrmOwnedStoreV1({
+  contract: "bazis.orm-owned-store/v1",
+  storeKey: "bazis.workflow.tasks",
+  formatVersion: 1,
+  ownedScope: { schema: "public", tablePrefix: "bazis_wf_task_" },
+});

package/core/workflow/tasks_module/model/WfTask.model.ts

@@ -0,0 +1,69 @@
+import { Column, Entity, Index, UUID } from "../../../orm";
+import type { FormSpec } from "../../../../library/workflow";
+
+/** `open` waits for someone, `claimed` is taken by one person, `completed` and `cancelled` are done. */
+export type TaskStatus = "open" | "claimed" | "completed" | "cancelled";
+
+/**
+ * A task for a person: a `userTask` step of an instance waiting for its form.
+ * Created from `WORKFLOW_TASK_REQUESTED`; references are text (other stores).
+ */
+@Index(["assignee", "status"])
+@Index(["partition", "status"])
+@Entity({ table: "bazis_wf_task_items" })
+export class WfTask {
+  @UUID({ version: "v7" })
+  id = "";
+
+  /** The waiting token: one task per token. */
+  @Index({ unique: true })
+  @Column({ type: "text" })
+  tokenId = "";
+
+  @Index()
+  @Column({ type: "text" })
+  instanceId = "";
+
+  @Column({ type: "text" })
+  processKey = "";
+
+  @Column({ type: "text" })
+  nodeId = "";
+
+  @Column({ type: "text", nullable: true })
+  partition: string | null = null;
+
+  @Column({ type: "text" })
+  title = "";
+
+  /** `role:<code>` or `user:<id>`. */
+  @Column({ type: "text" })
+  assignee = "";
+
+  @Column({ type: "json", nullable: true })
+  form: FormSpec | null = null;
+
+  @Column({ type: "datetime", nullable: true })
+  dueAt: Date | null = null;
+
+  @Column({ type: "text" })
+  status: TaskStatus = "open";
+
+  @Column({ type: "text", nullable: true })
+  claimedById: string | null = null;
+
+  @Column({ type: "datetime", nullable: true })
+  claimedAt: Date | null = null;
+
+  @Column({ type: "text", nullable: true })
+  completedById: string | null = null;
+
+  @Column({ type: "datetime", nullable: true })
+  completedAt: Date | null = null;
+
+  @Column({ type: "json", nullable: true })
+  output: Record<string, unknown> | null = null;
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+}