bazis 0.130.0 → 0.131.0

package/core/workflow/internal/http.ts

@@ -1,12 +1,15 @@
 import { IAccess, type AccessObject, type SubjectAccess } from "../../access";
 import { ForbiddenError, type HttpContext } from "../../http";
-import type { WorkflowActor } from "../contracts/types";
+import { frameworkBadRequest } from "../../http/Errors/HttpError";
+import { ListQueryError, parseListQuery, type ListQuery, type ListQueryOptions, type ListQueryProblem } from "../../../library/jsonapi";
+import type { WorkflowActor, WorkflowPaging, WorkflowRequest } from "../contracts/types";
 import { WorkflowError } from "../contracts/WorkflowError";
 
 /** Who calls a route: their rights and how they are recorded as an actor. */
 export interface WorkflowCaller {
   readonly access: SubjectAccess;
   readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest;
 }
 
 /**
@@ -20,7 +23,7 @@ export async function callerOf(ctx: HttpContext, permission?: string, object?: A
   if (permission !== undefined && !await access.can(permission, object)) throw new ForbiddenError();
   const sub = access.subject.sub;
   const [id = sub.slice(sub.lastIndexOf(":") + 1)] = await access.ownerIds();
-  return { access, actor: { kind: "user", id } };
+  return { access, actor: { kind: "user", id }, request: { ip: ctx.clientIp ?? null, userAgent: ctx.header("user-agent") ?? null } };
 }
 
 /** A route parameter as a string. */
@@ -64,7 +67,33 @@ export function optionalInteger(value: unknown, name: string): number | undefine
   return number as number;
 }
 
-/** `limit` and `offset` of a list query. */
-export function pagingQuery(ctx: HttpContext): { limit?: number; offset?: number } {
-  return { limit: optionalInteger(ctx.query("limit"), "limit"), offset: optionalInteger(ctx.query("offset"), "offset") };
+/**
+ * The list query of a route: `filter[...]`, `sort`, `page[...]`; anything
+ * `options` does not list is 400. Each filter here names one service option, so
+ * OR groups and a field filtered twice are refused rather than half applied.
+ */
+export function listQuery(ctx: HttpContext, options: Pick<ListQueryOptions, "filter" | "sort">): ListQuery {
+  try {
+    const list = parseListQuery(ctx.url.searchParams, { ...options, page: { defaultSize: 50, maxSize: 200 } });
+    const problems: ListQueryProblem[] = list.or.length > 0 ? [{ parameter: "filter[or]", message: "OR groups are not supported here" }] : [];
+    for (const [index, { field }] of list.filters.entries()) {
+      if (list.filters.findIndex((rule) => rule.field === field) !== index) problems.push({ parameter: `filter[${field}]`, message: "the field is filtered twice" });
+    }
+    if (problems.length > 0) throw new ListQueryError(problems);
+    return list;
+  } catch (error) {
+    if (error instanceof ListQueryError) throw frameworkBadRequest("invalidListQuery", undefined, error.problems);
+    throw error;
+  }
+}
+
+/** The page and order of a list query, for a list operation. */
+export function pagingOfList(list: ListQuery): WorkflowPaging {
+  return { limit: list.page.limit, offset: list.page.offset, ...(list.sort.length === 0 ? {} : { sort: list.sort }) };
+}
+
+/** The value of `filter[field]`. */
+export function filterOf(list: ListQuery, field: string): string | undefined {
+  const value = list.filters.find((rule) => rule.field === field)?.value;
+  return Array.isArray(value) ? value.join(",") : value as string | undefined;
 }

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

@@ -1,6 +1,7 @@
 import { createEventToken } from "../../../kernel";
 import type { FormSpec } from "../../../../library/workflow";
-import type { InstanceStatus } from "../model/WfInstance.model";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
+import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
 
 /** A token reached a user task. Published after the step commits. */
 export interface WorkflowTaskRequested {
@@ -37,7 +38,33 @@ export interface WorkflowInstancesDeleted {
   readonly instanceIds: readonly string[];
 }
 
+/** What the audit events of an instance share. Published after the commit. */
+interface WorkflowInstanceAudit {
+  readonly instanceId: string;
+  readonly processKey: string;
+  readonly partition: string | null;
+  readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest | null;
+}
+
+/** An instance started: by hand, from an event or on schedule. */
+export interface WorkflowInstanceStarted extends WorkflowInstanceAudit {
+  readonly version: number;
+  readonly businessKey: string | null;
+  readonly startedVia: StartedVia;
+}
+
+export interface WorkflowInstanceCancelled extends WorkflowInstanceAudit {
+  readonly reason: string | null;
+}
+
+/** The failed steps of an instance run again. */
+export type WorkflowInstanceRetried = WorkflowInstanceAudit;
+
 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");
+export const WORKFLOW_INSTANCE_STARTED = createEventToken<WorkflowInstanceStarted>("workflow.instance-started");
+export const WORKFLOW_INSTANCE_CANCELLED = createEventToken<WorkflowInstanceCancelled>("workflow.instance-cancelled");
+export const WORKFLOW_INSTANCE_RETRIED = createEventToken<WorkflowInstanceRetried>("workflow.instance-retried");

package/core/workflow/runtime_module/http/Events.controller.ts

@@ -15,11 +15,12 @@ export class EventsController {
     const eventKey = param(ctx, "eventKey");
     const request = await body(ctx);
     const partition = optionalString(request.partition, "partition") ?? null;
-    const { actor } = await callerOf(ctx, "workflow.events.emit", { scope: partition, event: eventKey });
+    const { actor, request: from } = await callerOf(ctx, "workflow.events.emit", { scope: partition, event: eventKey });
     const result = await this.runtime.emit(eventKey, request.payload ?? {}, {
       correlation: optionalString(request.correlation, "correlation") ?? null,
       partition,
       actor,
+      request: from,
     });
     ctx.res.status(202);
     return result;

package/core/workflow/runtime_module/http/Instances.controller.ts

@@ -1,7 +1,8 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
 import { can, type AccessObject } from "../../../access";
 import { Authorize, Controller, Created, Get, Post, type HttpContext } from "../../../http";
-import { body, callerOf, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import { buildListDocument } from "../../../../library/jsonapi";
+import { body, callerOf, filterOf, listQuery, optionalString, pagingOfList, param, requiredString } from "../../internal/http";
 import type { InstanceStatus } from "../model/WfInstance.model";
 import { IWorkflowRuntime, type InstanceSummary } from "../services/IWorkflowRuntime.service";
 
@@ -16,12 +17,13 @@ export class InstancesController {
     const request = await body(ctx);
     const processKey = requiredString(request.processKey, "processKey", 64);
     const partition = optionalString(request.partition, "partition") ?? null;
-    const { actor } = await callerOf(ctx, "workflow.instances.start", { scope: partition, process: processKey });
+    const { actor, request: from } = await callerOf(ctx, "workflow.instances.start", { scope: partition, process: processKey });
     const instance = await this.runtime.start(processKey, {
       input: request.input,
       partition,
       businessKey: optionalString(request.businessKey, "businessKey") ?? null,
       actor,
+      request: from,
     });
     return Created(`${ctx.path}/${instance.id}`, instance);
   }
@@ -30,16 +32,20 @@ export class InstancesController {
   @Authorize(can("workflow.instances.read"))
   async list(ctx: HttpContext) {
     const { access } = await callerOf(ctx);
+    const list = listQuery(ctx, {
+      filter: { partition: ["eq"], processKey: ["eq"], status: ["eq"], businessKey: ["eq"], startedById: ["eq"] },
+      sort: ["createdAt", "endedAt", "status", "processKey"],
+    });
     const page = await this.runtime.instances({
-      ...pagingQuery(ctx),
+      ...pagingOfList(list),
       access: await access.filter("workflow.instances.read"),
-      partition: optionalString(ctx.query("partition"), "partition"),
-      processKey: optionalString(ctx.query("processKey"), "processKey"),
-      status: optionalString(ctx.query("status"), "status") as InstanceStatus | undefined,
-      businessKey: optionalString(ctx.query("businessKey"), "businessKey"),
-      startedById: optionalString(ctx.query("startedById"), "startedById"),
+      partition: filterOf(list, "partition"),
+      processKey: filterOf(list, "processKey"),
+      status: filterOf(list, "status") as InstanceStatus | undefined,
+      businessKey: filterOf(list, "businessKey"),
+      startedById: filterOf(list, "startedById"),
     });
-    return { data: page.items, meta: { total: page.total } };
+    return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
   }
 
   @Get(":id")
@@ -63,16 +69,16 @@ export class InstancesController {
   async cancel(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
     const request = await body(ctx);
-    const { actor } = await callerOf(ctx, "workflow.instances.manage", objectOf(instance));
-    return await this.runtime.cancel(instance.id, { reason: optionalString(request.reason, "reason", 1000) ?? null, actor });
+    const { actor, request: from } = await callerOf(ctx, "workflow.instances.manage", objectOf(instance));
+    return await this.runtime.cancel(instance.id, { reason: optionalString(request.reason, "reason", 1000) ?? null, actor, request: from });
   }
 
   @Post(":id/retry")
   @Authorize(can("workflow.instances.manage"))
   async retry(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
-    const { actor } = await callerOf(ctx, "workflow.instances.manage", objectOf(instance));
-    return await this.runtime.retry(instance.id, { actor });
+    const { actor, request } = await callerOf(ctx, "workflow.instances.manage", objectOf(instance));
+    return await this.runtime.retry(instance.id, { actor, request });
   }
 }
 contextOnlyController(InstancesController);

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

@@ -1,5 +1,6 @@
 import type { AgentToolResult } from "../../../agent";
 import { durationMs, resolveInput } from "../../../../library/workflow";
+import type { WorkflowToolMetadata } from "../../contracts/types";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
@@ -36,7 +37,7 @@ export class ToolStep {
       : await runner.run(name, input, {
         idempotencyKey: token.id,
         actor: { kind: instance.startedByKind, id: instance.startedById },
-        metadata: { instanceId: instance.id, partition: instance.partition, processKey: instance.processKey, nodeId: token.nodeId },
+        metadata: { instanceId: instance.id, processKey: instance.processKey, nodeId: token.nodeId, partition: instance.partition, test: false } satisfies WorkflowToolMetadata,
         signal,
       });
 

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

@@ -1,10 +1,10 @@
-import type { ServiceProvider } from "../../../di";
-import { EventBus, type EventToken, type Logger } from "../../../kernel";
+import type { EventToken } 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 { WorkflowActor, WorkflowRequest } 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 { WorkflowEvents } from "../../internal/WorkflowEvents";
+import { WORKFLOW_INSTANCE_CANCELLED, WORKFLOW_INSTANCE_FINISHED, WORKFLOW_INSTANCE_RETRIED, WORKFLOW_INSTANCE_STARTED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED } from "../events/Runtime.events";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import { WfHistory, type HistoryType } from "../model/WfHistory.model";
 import { WfInstance, type StartedVia } from "../model/WfInstance.model";
@@ -36,6 +36,8 @@ export interface BeginOptions {
   readonly businessKey: string | null;
   readonly startedVia: StartedVia;
   readonly actor: WorkflowActor;
+  /** Where the start came from; `null` for code, schedules and the worker. */
+  readonly request?: WorkflowRequest | null;
 }
 
 const LIVE = new Set(["active", "waiting", "failed"]);
@@ -51,11 +53,8 @@ export class WorkflowEngine {
     private readonly db: RuntimeDbContext,
     private readonly definitions: IWorkflowDefinitions,
     private readonly graphs: GraphCache,
-    private readonly events: EventBus,
-    /** The scope of the engine: event handlers run in it. */
-    private readonly scope: ServiceProvider,
+    private readonly events: WorkflowEvents,
     private readonly clock: WorkflowClock,
-    private readonly logger?: Logger,
   ) {}
 
   /** The engine's time ({@link WorkflowClock}). */
@@ -97,6 +96,10 @@ export class WorkflowEngine {
       await this.db.saveChanges();
       const step: Step = { instance, tokens: [], graph, events: [] };
       this.history(step, null, null, "started", { via: options.startedVia }, options.actor);
+      step.events.push({
+        event: WORKFLOW_INSTANCE_STARTED as EventToken<unknown>,
+        payload: { instanceId: instance.id, processKey: graph.processKey, version: graph.version, partition: options.partition, businessKey: options.businessKey, startedVia: options.startedVia, actor: options.actor, request: options.request ?? null },
+      });
       await this.advance(step, [this.spawn(step, startNodeId, null)]);
       await this.db.saveChanges();
       this.publishAfter(transaction, step);
@@ -231,8 +234,12 @@ export class WorkflowEngine {
   }
 
   /** Retries the failed steps: their tokens are back on their nodes and the instance runs again. */
-  async retry(step: Step, actor: WorkflowActor): Promise<void> {
+  async retry(step: Step, actor: WorkflowActor, request: WorkflowRequest | null = null): Promise<void> {
     const failed = step.tokens.filter((t) => t.status === "failed");
+    step.events.push({
+      event: WORKFLOW_INSTANCE_RETRIED as EventToken<unknown>,
+      payload: { instanceId: step.instance.id, processKey: step.instance.processKey, partition: step.instance.partition, actor, request },
+    });
     step.instance.status = "running";
     step.instance.error = null;
     for (const token of failed) {
@@ -243,8 +250,12 @@ export class WorkflowEngine {
   }
 
   /** Closes every live token, job and subscription; the application drops the tasks on `WORKFLOW_TOKEN_CLOSED`. */
-  async cancel(step: Step, reason: string | null, actor: WorkflowActor): Promise<void> {
+  async cancel(step: Step, reason: string | null, actor: WorkflowActor, request: WorkflowRequest | null = null): Promise<void> {
     const open = step.tokens.filter((t) => LIVE.has(t.status));
+    step.events.push({
+      event: WORKFLOW_INSTANCE_CANCELLED as EventToken<unknown>,
+      payload: { instanceId: step.instance.id, processKey: step.instance.processKey, partition: step.instance.partition, reason, actor, request },
+    });
     for (const token of open) {
       token.status = "cancelled";
       token.endedAt = this.now();
@@ -493,21 +504,12 @@ export class WorkflowEngine {
     });
   }
 
-  /**
-   * Events go out after the commit, so a handler never sees a step that rolled
-   * back. A failing handler is logged: the step is already saved.
-   */
+  /** Events go out after the commit, so a handler never sees a step that rolled back. */
   private publishAfter(transaction: { afterCommit(callback: () => void | Promise<void>): void }, step: Step): void {
     if (step.events.length === 0) return;
     const events = [...step.events];
     transaction.afterCommit(async () => {
-      for (const { event, payload } of events) {
-        try {
-          await this.events.publishScoped(this.scope, event, payload);
-        } catch (error) {
-          this.logger?.error("workflow event handler failed", { event: event.name, instance: step.instance.id, error: error instanceof Error ? error.message : String(error) });
-        }
-      }
+      for (const { event, payload } of events) await this.events.publish(event, payload);
     });
   }
 }

package/core/workflow/runtime_module/services/IWorkflowRuntime.service.ts

@@ -1,11 +1,11 @@
 import type { AccessFilter } from "../../../access";
 import type { FormIssue } from "../../../../library/workflow";
-import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { HistoryType } from "../model/WfHistory.model";
 import type { InstanceStatus, StartedVia } from "../model/WfInstance.model";
 import type { TokenStatus } from "../model/WfToken.model";
 
-export interface StartInstance {
+export interface StartInstance extends WorkflowAuditOptions {
   readonly input?: unknown;
   /** The application's scope: a space, an organization. */
   readonly partition?: string | null;
@@ -15,6 +15,15 @@ export interface StartInstance {
   readonly actor: WorkflowActor;
 }
 
+export interface CancelInstance extends WorkflowAuditOptions {
+  readonly reason?: string | null;
+  readonly actor: WorkflowActor;
+}
+
+export interface RetryInstance extends WorkflowAuditOptions {
+  readonly actor: WorkflowActor;
+}
+
 export interface InstanceSummary {
   readonly id: string;
   readonly processKey: string;
@@ -57,7 +66,7 @@ export interface HistoryEntry {
   readonly at: Date;
 }
 
-export interface EmitOptions {
+export interface EmitOptions extends WorkflowAuditOptions {
   /** Which waits it is for: `order:42`. Waits without a correlation take any event of the key. */
   readonly correlation?: string | null;
   /** Only the waits of this partition; it is also the partition of instances the event starts. */
@@ -92,9 +101,9 @@ export interface InstanceListQuery extends WorkflowPaging {
 export abstract class IWorkflowRuntime {
   /** Starts the latest version of a process from its manual start. */
   abstract start(processKey: string, options: StartInstance): Promise<InstanceDetails>;
-  abstract cancel(instanceId: string, options: { readonly reason?: string | null; readonly actor: WorkflowActor }): Promise<InstanceDetails>;
+  abstract cancel(instanceId: string, options: CancelInstance): Promise<InstanceDetails>;
   /** Retries the failed steps of a `failed` instance. */
-  abstract retry(instanceId: string, options: { readonly actor: WorkflowActor }): Promise<InstanceDetails>;
+  abstract retry(instanceId: string, options: RetryInstance): Promise<InstanceDetails>;
   /** Finishes a user task's wait with the form output and moves on; `wrong_status` when the token no longer waits. */
   abstract completeToken(tokenId: string, output: unknown, actor: WorkflowActor): Promise<InstanceDetails>;
   /**

package/core/workflow/runtime_module/services/WorkflowRuntime.service.ts

@@ -1,6 +1,7 @@
 import { grantsToWhere } from "../../../access";
+import { paginate } from "../../../orm";
 import type { FormIssue, FormSpec } from "../../../../library/workflow";
-import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
+import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import type { ServiceProvider } from "../../../di";
 import { WorkflowInputValidator } from "../../contracts/WorkflowInputValidator";
@@ -12,12 +13,14 @@ import type { WfInstance } from "../model/WfInstance.model";
 import type { WfToken } from "../model/WfToken.model";
 import {
   IWorkflowRuntime,
+  type CancelInstance,
   type EmitOptions,
   type EmitResult,
   type HistoryEntry,
   type InstanceDetails,
   type InstanceListQuery,
   type InstanceSummary,
+  type RetryInstance,
   type StartInstance,
 } from "./IWorkflowRuntime.service";
 
@@ -44,29 +47,29 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
     const { value, issues } = await this.validator().validate(version.document.input, options.input, { purpose: "input", processKey, partition });
     if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
-    const id = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor });
+    const id = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
     return await this.instance(id);
   }
 
-  async cancel(instanceId: string, options: { readonly reason?: string | null; readonly actor: WorkflowActor }): Promise<InstanceDetails> {
+  async cancel(instanceId: string, options: CancelInstance): Promise<InstanceDetails> {
     actorOf(options.actor);
     const reason = optionalText(options.reason, "reason", 1000);
     if (!isUuid(instanceId)) throw notFound(instanceId);
     const done = await this.engine.inStep(instanceId, async (step) => {
       if (step.instance.status !== "running" && step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Instance is ${step.instance.status}`);
-      await this.engine.cancel(step, reason, options.actor);
+      await this.engine.cancel(step, reason, options.actor, options.request ?? null);
       return true;
     });
     if (done === null) throw notFound(instanceId);
     return await this.instance(instanceId);
   }
 
-  async retry(instanceId: string, options: { readonly actor: WorkflowActor }): Promise<InstanceDetails> {
+  async retry(instanceId: string, options: RetryInstance): Promise<InstanceDetails> {
     actorOf(options.actor);
     if (!isUuid(instanceId)) throw notFound(instanceId);
     const done = await this.engine.inStep(instanceId, async (step) => {
       if (step.instance.status !== "failed") throw new WorkflowError("wrong_status", `Only a failed instance is retried; this one is ${step.instance.status}`);
-      await this.engine.retry(step, options.actor);
+      await this.engine.retry(step, options.actor, options.request ?? null);
       return true;
     });
     if (done === null) throw notFound(instanceId);
@@ -126,14 +129,13 @@ export class WorkflowRuntime extends IWorkflowRuntime {
           rejected.push({ processKey: version.key, issues });
           continue;
         }
-        started.push(await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor }));
+        started.push(await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null }));
       }
     }
     return { started, continued: [...continued], rejected };
   }
 
   async instances(query: InstanceListQuery = {}): Promise<WorkflowPage<InstanceSummary>> {
-    const { limit, offset } = pagingOf(query);
     if (query.status !== undefined && !STATUSES.has(query.status)) throw new WorkflowError("invalid_input", "status must be running, completed, cancelled or failed");
     const where = query.access === undefined ? "all" : grantsToWhere(query.access);
     if (where === "none") return { items: [], total: 0 };
@@ -144,9 +146,8 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (query.processKey !== undefined) source = source.where((i) => i.processKey.eq(query.processKey!));
     if (query.businessKey !== undefined) source = source.where((i) => i.businessKey.eq(query.businessKey!));
     if (query.startedById !== undefined) source = source.where((i) => i.startedById.eq(query.startedById!));
-    const total = await source.count();
-    const rows = await source.orderByDescending((i) => i.id).skip(offset).take(limit).toList();
-    return { items: rows.map(summaryOf), total };
+    const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "desc" }));
+    return { items: items.map(summaryOf), total };
   }
 
   async instance(instanceId: string): Promise<InstanceDetails> {

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

@@ -0,0 +1,15 @@
+import { createEventToken } from "../../../kernel";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
+
+/** A person filled a task's form, for the application's audit. Published after it is saved. */
+export interface WorkflowTaskCompleted {
+  readonly taskId: string;
+  readonly instanceId: string;
+  readonly processKey: string;
+  readonly nodeId: string;
+  readonly partition: string | null;
+  readonly actor: WorkflowActor;
+  readonly request: WorkflowRequest | null;
+}
+
+export const WORKFLOW_TASK_COMPLETED = createEventToken<WorkflowTaskCompleted>("workflow.task-completed");

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

@@ -1,9 +1,10 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
 import { can } from "../../../access";
 import { Authorize, Controller, Get, Post, type HttpContext } from "../../../http";
-import type { WorkflowActor } from "../../contracts/types";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
-import { body, callerOf, optionalString, pagingQuery, param } from "../../internal/http";
+import { buildListDocument } from "../../../../library/jsonapi";
+import { body, callerOf, filterOf, listQuery, pagingOfList, param } from "../../internal/http";
 import type { TaskStatus } from "../model/WfTask.model";
 import { IWorkflowTasks, type TaskDetails } from "../services/IWorkflowTasks.service";
 
@@ -19,21 +20,22 @@ export class TasksController {
   @Get()
   @Authorize(can("workflow.tasks.work"))
   async list(ctx: HttpContext) {
-    const partition = optionalString(ctx.query("partition"), "partition");
     const { access, actor } = await callerOf(ctx);
-    const status = ctx.query("status");
+    const list = listQuery(ctx, { filter: { partition: ["eq"], processKey: ["eq"], status: ["eq", "in"] }, sort: ["createdAt", "dueAt", "status", "processKey"] });
+    const partition = filterOf(list, "partition");
+    const status = filterOf(list, "status");
     const statuses = status === undefined ? {} : { status: status.split(",") as TaskStatus[] };
     const page = await this.tasks.list({
-      ...pagingQuery(ctx),
+      ...pagingOfList(list),
       ...statuses,
       // Addressees are per partition and counted now, not when the task was created.
       addressees: await access.principals(partition === undefined ? await this.tasks.partitions(statuses) : [partition]),
       actor,
       access: await access.filter("workflow.tasks.work"),
       partition,
-      processKey: optionalString(ctx.query("processKey"), "processKey"),
+      processKey: filterOf(list, "processKey"),
     });
-    return { data: page.items, meta: { total: page.total } };
+    return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
   }
 
   @Get(":id")
@@ -59,18 +61,18 @@ export class TasksController {
   @Post(":id/complete")
   @Authorize(can("workflow.tasks.work"))
   async complete(ctx: HttpContext) {
-    const { task, actor } = await this.visible(ctx);
+    const { task, actor, request: from } = await this.visible(ctx);
     const request = await body(ctx);
-    return await this.tasks.complete(task.id, request.output ?? {}, actor);
+    return await this.tasks.complete(task.id, request.output ?? {}, actor, { request: from });
   }
 
   /** The task if the caller may see it: addressed to one of their principals or claimed by them. */
-  private async visible(ctx: HttpContext): Promise<{ task: TaskDetails; actor: WorkflowActor }> {
+  private async visible(ctx: HttpContext): Promise<{ task: TaskDetails; actor: WorkflowActor; request: WorkflowRequest }> {
     const task = await this.tasks.get(param(ctx, "id"));
-    const { access, actor } = await callerOf(ctx, "workflow.tasks.work", { scope: task.partition, process: task.processKey });
+    const { access, actor, request } = await callerOf(ctx, "workflow.tasks.work", { scope: task.partition, process: task.processKey });
     const addressees = await access.principals([task.partition]);
     if (!addressees.some(({ principals }) => principals.includes(task.assignee)) && task.claimedBy !== actor.id) throw new WorkflowError("not_found", `Task ${task.id} does not exist`);
-    return { task, actor };
+    return { task, actor, request };
   }
 }
 contextOnlyController(TasksController);

package/core/workflow/tasks_module/services/IWorkflowTasks.service.ts

@@ -1,6 +1,6 @@
 import type { FormSpec } from "../../../../library/workflow";
 import type { AccessFilter, ScopePrincipals } from "../../../access";
-import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { TaskStatus } from "../model/WfTask.model";
 
 export interface TaskDetails {
@@ -53,5 +53,5 @@ export abstract class IWorkflowTasks {
   /** Gives a claimed task back. */
   abstract release(taskId: string, actor: WorkflowActor): Promise<TaskDetails>;
   /** Fills the form: the process moves on. */
-  abstract complete(taskId: string, output: unknown, actor: WorkflowActor): Promise<TaskDetails>;
+  abstract complete(taskId: string, output: unknown, actor: WorkflowActor, options?: WorkflowAuditOptions): Promise<TaskDetails>;
 }

package/core/workflow/tasks_module/services/WorkflowTasks.service.ts

@@ -1,8 +1,11 @@
 import { grantsToWhere, type ScopePrincipals } from "../../../access";
-import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
+import { paginate } from "../../../orm";
+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 { IWorkflowRuntime } from "../../runtime_module/services/IWorkflowRuntime.service";
+import { WORKFLOW_TASK_COMPLETED } from "../events/Tasks.events";
 import type { TasksDbContext } from "../model/Tasks.dbContext";
 import { WfTask, type TaskStatus } from "../model/WfTask.model";
 import { IWorkflowTasks, type TaskDetails, type TaskListQuery } from "./IWorkflowTasks.service";
@@ -14,12 +17,12 @@ export class WorkflowTasks extends IWorkflowTasks {
     private readonly db: TasksDbContext,
     private readonly runtime: IWorkflowRuntime,
     private readonly clock: WorkflowClock,
+    private readonly events: WorkflowEvents,
   ) {
     super();
   }
 
   async list(query: TaskListQuery): Promise<WorkflowPage<TaskDetails>> {
-    const { limit, offset } = pagingOf(query);
     const statuses = statusesOf(query.status);
     const groups = groupByPrincipals(query.addressees);
     const mine = query.actor?.id;
@@ -38,9 +41,8 @@ export class WorkflowTasks extends IWorkflowTasks {
     });
     if (query.partition !== undefined) source = source.where((t) => t.partition.eq(query.partition!));
     if (query.processKey !== undefined) source = source.where((t) => t.processKey.eq(query.processKey!));
-    const total = await source.count();
-    const rows = await source.orderBy((t) => t.id).skip(offset).take(limit).toList();
-    return { items: rows.map(detailsOf), total };
+    const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "asc" }));
+    return { items: items.map(detailsOf), total };
   }
 
   async partitions(query: { readonly status?: readonly TaskStatus[] } = {}): Promise<readonly (string | null)[]> {
@@ -79,7 +81,7 @@ export class WorkflowTasks extends IWorkflowTasks {
     });
   }
 
-  async complete(taskId: string, output: unknown, actor: WorkflowActor): Promise<TaskDetails> {
+  async complete(taskId: string, output: unknown, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<TaskDetails> {
     const task = await this.task(taskId, false);
     if (task.status === "claimed" && task.claimedById !== actor.id) throw new WorkflowError("conflict", "The task is taken by someone else");
     if (task.status !== "open" && task.status !== "claimed") throw new WorkflowError("wrong_status", `The task is ${task.status}`);
@@ -98,6 +100,7 @@ export class WorkflowTasks extends IWorkflowTasks {
       completedAt: this.clock.now(),
       output: typeof saved === "object" && saved !== null && !Array.isArray(saved) ? saved as Record<string, unknown> : null,
     });
+    await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
     return await this.get(task.id);
   }
 

package/library/openapi/codegen.ts

@@ -686,6 +686,15 @@ function applyValidatorOptions(schema: OpenApiCodegenSchema, options: Record<str
     out.type = "string";
     out.pattern = options.pattern;
   }
+  if (typeof options.ref === "string") {
+    out["x-ref"] = options.ref;
+  }
+  if (typeof options.refKeys === "string") {
+    out["x-ref-keys"] = options.refKeys;
+  }
+  if (typeof options.refScope === "string") {
+    out["x-ref-scope"] = options.refScope;
+  }
   return out;
 }
 

package/library/validation/types/ValidatorOptions.ts

@@ -150,4 +150,14 @@ export interface ValidatorOptions {
    * enums are ignored).
    */
   enumType?: Record<string, string | number>;
+
+  // ── Schema ───────────────────────────────────────────────────────────────
+  // Literals that go to the generated JSON Schema; they check nothing here.
+
+  /** The value is a reference of this kind (`x-ref`): `dm.table`. */
+  ref?: string;
+  /** The keys of the object are references of this kind (`x-ref-keys`): fields of a table. */
+  refKeys?: string;
+  /** JSON Pointer to the sibling input that sets their area (`x-ref-scope`): `/table`. */
+  refScope?: `/${string}`;
 }