bazis 0.129.0 → 0.131.0

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,10 +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;
@@ -14,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;
@@ -56,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. */
@@ -75,6 +85,8 @@ export interface EmitResult {
 }
 
 export interface InstanceListQuery extends WorkflowPaging {
+  /** Which instances the caller may see, from `IAccess`; without it the calling code has decided. */
+  readonly access?: AccessFilter;
   readonly partition?: string;
   readonly status?: InstanceStatus;
   readonly processKey?: string;
@@ -89,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,5 +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";
@@ -11,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";
 
@@ -43,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);
@@ -125,24 +129,25 @@ 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 };
     let source = this.db.instances.asNoTracking();
+    if (where !== "all") source = source.where(() => where);
     if (query.partition !== undefined) source = source.where((i) => i.partition.eq(query.partition!));
     if (query.status !== undefined) source = source.where((i) => i.status.eq(query.status!));
     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/WorkflowTasks.module.ts

@@ -1,7 +1,9 @@
+import { AccessModule } from "../../access";
 import { Module, scoped } from "../../di";
 import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
 import { withEventSubscribers } from "../../kernel";
 import { WorkflowRuntimeModule } from "../runtime_module/WorkflowRuntime.module";
+import { tasksPermissions } from "./access/Tasks.permissions";
 import { TaskEvents } from "./events/TaskEvents";
 import { TasksController } from "./http/Tasks.controller";
 import { TasksDbContext, tasksStore } from "./model/Tasks.dbContext";
@@ -13,7 +15,8 @@ import { WorkflowTasks } from "./services/WorkflowTasks.service";
  * Tasks for people: the inbox of `userTask` steps ([passport](MODULE.md)).
  */
 @Module({
-  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule],
+  imports: [AccessModule, WorkflowDefinitionsModule, WorkflowRuntimeModule],
+  permissions: tasksPermissions,
   ormBazis: { context: TasksDbContext, entities: [WfTask], ownedStore: tasksStore, registerRepositories: false },
   providers: [
     scoped(IWorkflowTasks, WorkflowTasks),

package/core/workflow/tasks_module/access/Tasks.permissions.ts

@@ -0,0 +1,13 @@
+import { definePermissions } from "../../../access";
+
+/**
+ * The right to work on tasks (WORKFLOW-002 §6.2). Which tasks are the
+ * subject's is decided by their addressees, not by an owner column.
+ */
+export const tasksPermissions = definePermissions({
+  "workflow.tasks.work": {
+    title: { en: "Work on tasks", ru: "Работать с задачами" },
+    scope: { column: "partition" },
+    on: { process: { ref: "workflow.process", column: "processKey" } },
+  },
+});

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,67 +1,78 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { Controller, Get, Post, type HttpContext } from "../../../http";
-import type { WorkflowActor } from "../../contracts/types";
+import { can } from "../../../access";
+import { Authorize, Controller, Get, Post, type HttpContext } from "../../../http";
+import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
-import { assigneesOf, authorize, body, 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";
 
 /**
- * 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.
+ * The caller's tasks (WORKFLOW-002 §6.2): those addressed to any of the
+ * subject's `principals` in the task's partition 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()
+  @Authorize(can("workflow.tasks.work"))
   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 { access, actor } = await callerOf(ctx);
+    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),
-      assignees: await assigneesOf(ctx, actor),
+      ...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,
-      ...(status === undefined ? {} : { status: status.split(",") as TaskStatus[] }),
+      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")
+  @Authorize(can("workflow.tasks.work"))
   async get(ctx: HttpContext) {
     return (await this.visible(ctx)).task;
   }
 
   @Post(":id/claim")
+  @Authorize(can("workflow.tasks.work"))
   async claim(ctx: HttpContext) {
     const { task, actor } = await this.visible(ctx);
     return await this.tasks.claim(task.id, actor);
   }
 
   @Post(":id/release")
+  @Authorize(can("workflow.tasks.work"))
   async release(ctx: HttpContext) {
     const { task, actor } = await this.visible(ctx);
     return await this.tasks.release(task.id, actor);
   }
 
   @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 assignees or claimed by them. */
-  private async visible(ctx: HttpContext): Promise<{ task: TaskDetails; actor: WorkflowActor }> {
+  /** 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; request: WorkflowRequest }> {
     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 };
+    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, request };
   }
 }
 contextOnlyController(TasksController);

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

@@ -1,5 +1,6 @@
 import type { FormSpec } from "../../../../library/workflow";
-import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { AccessFilter, ScopePrincipals } from "../../../access";
+import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { TaskStatus } from "../model/WfTask.model";
 
 export interface TaskDetails {
@@ -23,10 +24,12 @@ export interface TaskDetails {
 }
 
 export interface TaskListQuery extends WorkflowPaging {
-  /** Tasks addressed to any of these (`role:support`, `user:42`), plus those the actor claimed. */
-  readonly assignees: readonly string[];
+  /** Tasks addressed to these (`role:support`, `user:42`) in their partition, plus those the actor claimed. */
+  readonly addressees: readonly ScopePrincipals[];
   /** Whose claimed tasks count as theirs. */
   readonly actor?: WorkflowActor;
+  /** Which tasks the caller may see, from `IAccess`; without it the calling code has decided. */
+  readonly access?: AccessFilter;
   /** `open` and `claimed` by default. */
   readonly status?: readonly TaskStatus[];
   readonly partition?: string;
@@ -40,13 +43,15 @@ export interface TaskListQuery extends WorkflowPaging {
  * by another person), `wrong_status`, `invalid_input` with the form issues.
  */
 export abstract class IWorkflowTasks {
-  /** The tasks of these assignees, oldest first. */
+  /** The tasks of these addressees, oldest first. */
   abstract list(query: TaskListQuery): Promise<WorkflowPage<TaskDetails>>;
+  /** The partitions that have tasks in these statuses (`open` and `claimed` by default): where to ask for addressees. */
+  abstract partitions(query?: { readonly status?: readonly TaskStatus[] }): Promise<readonly (string | null)[]>;
   abstract get(taskId: string): Promise<TaskDetails>;
   /** Takes an open task: nobody else can complete it until it is released. */
   abstract claim(taskId: string, actor: WorkflowActor): Promise<TaskDetails>;
   /** 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,7 +1,11 @@
-import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
+import { grantsToWhere, type ScopePrincipals } from "../../../access";
+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";
@@ -13,28 +17,38 @@ 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 = [...(query.status ?? ["open", "claimed"])];
-    if (statuses.length === 0 || statuses.some((status) => !STATUSES.has(status))) throw new WorkflowError("invalid_input", "status must be open, claimed, completed or cancelled");
-    const assignees = [...query.assignees];
+    const statuses = statusesOf(query.status);
+    const groups = groupByPrincipals(query.addressees);
     const mine = query.actor?.id;
-    if (assignees.length === 0 && mine === undefined) return { items: [], total: 0 };
+    const where = query.access === undefined ? "all" : grantsToWhere(query.access);
+    if (where === "none" || (groups.length === 0 && mine === undefined)) return { items: [], total: 0 };
     let source = this.db.tasks.asNoTracking().where((t) => t.status.in(statuses));
-    source = mine === undefined
-      ? source.where((t) => t.assignee.in(assignees))
-      : assignees.length === 0
-        ? source.where((t) => t.claimedById.eq(mine))
-        : source.where((t) => t.assignee.in(assignees).or(t.claimedById.eq(mine)));
+    if (where !== "all") source = source.where(() => where);
+    source = source.where((t) => {
+      const theirs = groups.map(({ scopes, principals }) => {
+        const named = scopes.filter((scope): scope is string => scope !== null);
+        const partition = !scopes.includes(null) ? t.partition.in(named) : named.length === 0 ? t.partition.isNull() : t.partition.isNull().or(t.partition.in(named));
+        return t.assignee.in(principals).and(partition);
+      });
+      if (mine !== undefined) theirs.push(t.claimedById.eq(mine));
+      return theirs.reduce((left, right) => left.or(right));
+    });
     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)[]> {
+    const statuses = statusesOf(query.status);
+    const rows = await this.db.database.querySqlRaw(`SELECT DISTINCT "partition" FROM "bazis_wf_task_items" WHERE "status" IN (${statuses.map((_, index) => `{${index}}`).join(", ")})`, ...statuses);
+    return rows.map((row) => row.partition as string | null);
   }
 
   async get(taskId: string): Promise<TaskDetails> {
@@ -67,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}`);
@@ -86,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);
   }
 
@@ -109,6 +124,26 @@ export class WorkflowTasks extends IWorkflowTasks {
   }
 }
 
+function statusesOf(status: readonly TaskStatus[] | undefined): TaskStatus[] {
+  const statuses = [...(status ?? ["open", "claimed"] as const)];
+  if (statuses.length === 0 || statuses.some((item) => !STATUSES.has(item))) throw new WorkflowError("invalid_input", "status must be open, claimed, completed or cancelled");
+  return statuses;
+}
+
+/** Partitions with the same addressees go together: usually all of them, so the query stays short. */
+function groupByPrincipals(addressees: readonly ScopePrincipals[]): { scopes: (string | null)[]; principals: string[] }[] {
+  const groups = new Map<string, { scopes: (string | null)[]; principals: string[] }>();
+  for (const { scope, principals } of addressees) {
+    if (principals.length === 0) continue;
+    const list = [...new Set(principals)].sort();
+    const key = JSON.stringify(list);
+    const group = groups.get(key);
+    if (group === undefined) groups.set(key, { scopes: [scope], principals: list });
+    else group.scopes.push(scope);
+  }
+  return [...groups.values()];
+}
+
 function notFound(taskId: string): WorkflowError {
   return new WorkflowError("not_found", `Task ${taskId} does not exist`);
 }

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}`;
 }

package/library/workflow/formFields.ts

@@ -19,7 +19,8 @@ export interface FormSpec {
 /** One problem of a value: which field and why. */
 export interface FormIssue {
   readonly field: string;
-  readonly code: "required" | "type" | "enum" | "unknown";
+  /** Built in: `required`, `type`, `enum`, `unknown`; an application's validator adds its own. */
+  readonly code: string;
   readonly message: string;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.129.0",
+  "version": "0.131.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",