bazis 0.129.0 → 0.131.0

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

@@ -1,13 +1,16 @@
+import { grantsToWhere } from "../../../access";
 import { createHash } from "node:crypto";
-import { UniqueViolationError } from "../../../orm";
+import { paginate, UniqueViolationError } from "../../../orm";
 import type { AgentToolContract } from "../../../agent";
 import { emptyProcess, hasErrors, validateProcess, type ProcessDocument, type ProcessIssue } from "../../../../library/workflow";
-import { isUuid, pagingOf, type WorkflowActor, type WorkflowPage } from "../../contracts/types";
+import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowAuditOptions, type WorkflowPage } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import { WorkflowError } from "../../contracts/WorkflowError";
+import type { WorkflowEvents } from "../../internal/WorkflowEvents";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { CodeProcessCatalog } from "../code/CodeProcessCatalog";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
+import { WORKFLOW_PROCESS_CHANGED, type ProcessChange } from "../events/Definitions.events";
 import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
 import { WfProcess } from "../model/WfProcess.model";
 import { WfVersion } from "../model/WfVersion.model";
@@ -17,6 +20,8 @@ import {
   type ProcessDetails,
   type ProcessListQuery,
   type ProcessSummary,
+  type SavedDraft,
+  type SaveDraftOptions,
   type UpdateProcess,
   type VersionDetails,
   type VersionSummary,
@@ -32,29 +37,31 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     private readonly workflowTools: WorkflowTools,
     private readonly code: CodeProcessCatalog,
     private readonly clock: WorkflowClock,
+    private readonly events: WorkflowEvents,
   ) {
     super();
   }
 
   async list(query: ProcessListQuery = {}): Promise<WorkflowPage<ProcessSummary>> {
-    const { limit, offset } = pagingOf(query);
+    const where = query.access === undefined ? "all" : grantsToWhere(query.access);
+    if (where === "none") return { items: [], total: 0 };
     let source = this.db.processes.asNoTracking();
+    if (where !== "all") source = source.where(() => where);
     if (query.archived === true) source = source.where((p) => p.archivedAt.isNotNull());
     if (query.archived === false) source = source.where((p) => p.archivedAt.isNull());
     if (query.search !== undefined && query.search.trim() !== "") {
       const text = query.search.trim();
       source = source.where((p) => p.key.contains(text, { ignoreCase: true }).or(p.title.contains(text, { ignoreCase: true })));
     }
-    const total = await source.count();
-    const rows = await source.orderBy((p) => p.key).skip(offset).take(limit).toList();
-    return { items: rows.map((row) => this.summaryOf(row)), total };
+    const { items, total } = await paginate(source, pageQueryOf(query, { field: "key", dir: "asc" }));
+    return { items: items.map((row) => this.summaryOf(row)), total };
   }
 
   async get(key: string): Promise<ProcessDetails> {
     return this.detailsOf(await this.process(key, false));
   }
 
-  async create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails> {
+  async create(process: CreateProcess, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<ProcessDetails> {
     if (typeof process.key !== "string" || !KEY.test(process.key)) throw new WorkflowError("invalid_input", "key must match ^[a-z][a-z0-9_.-]{0,63}$");
     const row = Object.assign(new WfProcess(), {
       key: process.key,
@@ -73,43 +80,57 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
       if (error instanceof UniqueViolationError) throw new WorkflowError("conflict", `Process ${process.key} already exists`);
       throw error;
     }
+    await this.changed("created", row.key, actor, options);
     return this.detailsOf(row);
   }
 
-  async update(key: string, changes: UpdateProcess, _actor: WorkflowActor): Promise<ProcessDetails> {
+  async update(key: string, changes: UpdateProcess, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<ProcessDetails> {
     const row = await this.process(key, true);
     const { archived, ...fields } = changes;
     if (Object.values(fields).some((value) => value !== undefined)) this.assertNotCode(key);
+    const before = { title: row.title, description: row.description, retentionDays: row.retentionDays, archived: row.archivedAt !== null };
     if (changes.title !== undefined) row.title = title(changes.title);
     if (changes.description !== undefined) row.description = description(changes.description);
     if (changes.retentionDays !== undefined) row.retentionDays = retention(changes.retentionDays);
     if (archived !== undefined) row.archivedAt = archived ? row.archivedAt ?? this.clock.now() : null;
     await this.db.saveChanges();
+    if (row.title !== before.title || row.description !== before.description || row.retentionDays !== before.retentionDays) await this.changed("updated", key, actor, options);
+    if (archived !== undefined && archived !== before.archived) await this.changed(archived ? "archived" : "restored", key, actor, options);
     return this.detailsOf(row);
   }
 
-  async saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }> {
+  async saveDraft(key: string, document: unknown, actor: WorkflowActor, options: SaveDraftOptions = {}): Promise<SavedDraft> {
     const issues = this.validate(document);
     if (issues.some((issue) => issue.code === "too_large")) throw new WorkflowError("invalid_document", "The document is too large", issues);
-    const row = await this.process(key, true);
-    this.assertNotCode(key);
-    row.draft = document;
-    row.draftUpdatedAt = this.clock.now();
-    row.draftUpdatedByKind = actor.kind;
-    row.draftUpdatedById = actor.id;
-    await this.db.saveChanges();
-    return { issues };
+    return await this.db.transactionScope(async (transaction) => {
+      const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
+      if (!row) throw notFound(key);
+      this.assertNotCode(key);
+      const previous = row.draftUpdatedAt?.getTime();
+      if (options.expected !== undefined && previous !== options.expected.getTime()) throw new WorkflowError("conflict", `The draft of ${key} was saved by someone else`);
+      // Later than the last save even within a millisecond: `expected` tells any two saves apart.
+      const draftUpdatedAt = new Date(Math.max(this.clock.now().getTime(), (previous ?? 0) + 1));
+      row.draft = document;
+      row.draftUpdatedAt = draftUpdatedAt;
+      row.draftUpdatedByKind = actor.kind;
+      row.draftUpdatedById = actor.id;
+      await this.db.saveChanges();
+      transaction.afterCommit(() => this.changed("draftSaved", key, actor, options));
+      return { issues, draftUpdatedAt };
+    });
   }
 
-  async publish(key: string, actor: WorkflowActor): Promise<VersionDetails> {
-    return await this.db.transactionScope(async () => {
+  async publish(key: string, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<VersionDetails> {
+    return await this.db.transactionScope(async (transaction) => {
       const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
       if (!row) throw notFound(key);
       this.assertNotCode(key);
       if (row.archivedAt !== null) throw new WorkflowError("archived", `Process ${key} is archived`);
       const issues = this.validate(row.draft);
       if (hasErrors(issues)) throw new WorkflowError("invalid_document", `Process ${key} has errors and cannot be published`, issues);
-      return (await this.publishDraft(row, actor)).version;
+      const { version, created } = await this.publishDraft(row, actor);
+      if (created) transaction.afterCommit(() => this.changed("published", key, actor, options, version.version));
+      return version;
     });
   }
 
@@ -120,7 +141,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
    * and unpublished. The caller has checked the documents with the Tools.
    */
   async publishCode(entries: readonly OwnedCodeProcess[]): Promise<readonly { readonly key: string; readonly version: number | null; readonly published: boolean }[]> {
-    return await this.db.transactionScope(async () => {
+    return await this.db.transactionScope(async (transaction) => {
       await this.db.database.querySqlRaw("SELECT pg_advisory_xact_lock(hashtext('bazis.workflow.code'))");
       const results: { key: string; version: number | null; published: boolean }[] = [];
       for (const { process } of [...entries].sort((a, b) => a.process.key.localeCompare(b.process.key))) {
@@ -128,6 +149,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
         if (!row) {
           row = Object.assign(new WfProcess(), { key: process.key });
           this.db.processes.add(row);
+          transaction.afterCommit(() => this.changed("created", process.key, CODE_ACTOR));
         }
         const fields = { title: title(process.title), description: description(process.description), retentionDays: retention(process.retentionDays) };
         if (row.title !== fields.title) row.title = fields.title;
@@ -145,6 +167,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
           continue;
         }
         const { version, created } = await this.publishDraft(row, CODE_ACTOR);
+        if (created) transaction.afterCommit(() => this.changed("published", process.key, CODE_ACTOR, {}, version.version));
         results.push({ key: row.key, version: version.version, published: created });
       }
       return results;
@@ -222,6 +245,10 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     return this.workflowTools.list();
   }
 
+  private async changed(change: ProcessChange, key: string, actor: WorkflowActor, options: WorkflowAuditOptions = {}, version: number | null = null): Promise<void> {
+    await this.events.publish(WORKFLOW_PROCESS_CHANGED, { change, key, version, actor, request: options.request ?? null });
+  }
+
   /** A process declared in code changes only through the code. */
   private assertNotCode(key: string): void {
     const module = this.code.moduleOf(key);

package/core/workflow/generated/deps.ts

@@ -5,12 +5,14 @@ import { DbContextOptions } from "../../../library/orm/DbContextOptions";
 import { ServiceProvider } from "../../di/ServiceProvider";
 import { EventBus } from "../../kernel/events/EventBus";
 import { WorkflowClock } from "../contracts/WorkflowClock";
+import { ProcessReferences } from "../definitions_module/access/Process.references";
 import { CodeProcessCatalog } from "../definitions_module/code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "../definitions_module/code/CodeProcessPublisher";
 import { ProcessesController } from "../definitions_module/http/Processes.controller";
 import { DefinitionsDbContext } from "../definitions_module/model/Definitions.dbContext";
 import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
 import { WorkflowDefinitions } from "../definitions_module/services/WorkflowDefinitions.service";
+import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { WorkflowRetention } from "../runtime_module/background/WorkflowRetention";
 import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
@@ -37,6 +39,7 @@ registerFrameworkClassDeps([
   [EventsController, [IWorkflowRuntime]],
   [InstancesController, [IWorkflowRuntime]],
   [ProcessesController, [IWorkflowDefinitions]],
+  [ProcessReferences, [DefinitionsDbContext]],
   [RuntimeDbContext, [DbContextOptions]],
   [Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions]],
   [TaskEvents, [TasksDbContext]],
@@ -44,11 +47,12 @@ registerFrameworkClassDeps([
   [TasksDbContext, [DbContextOptions]],
   [TimerStep, [RuntimeDbContext, WorkflowEngine]],
   [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools]],
-  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock]],
-  [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, EventBus, ServiceProvider, WorkflowClock, "optional:Logger"]],
+  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents]],
+  [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
+  [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
   [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
   [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider]],
-  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock]],
+  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock, WorkflowEvents]],
   [WorkflowTools, [ServiceProvider]],
   [WorkflowWorker, [ServiceProvider, "Config:workflow"]],
 ]);

package/core/workflow/index.ts

@@ -14,6 +14,8 @@ export { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefiniti
 export { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
 export { WorkflowTasksModule } from "./tasks_module/WorkflowTasks.module";
 export { IWorkflowTasks, type TaskDetails, type TaskListQuery } from "./tasks_module/services/IWorkflowTasks.service";
+export { WORKFLOW_TASK_COMPLETED, type WorkflowTaskCompleted } from "./tasks_module/events/Tasks.events";
+export { WORKFLOW_PROCESS_CHANGED, type ProcessChange, type WorkflowProcessChanged } from "./definitions_module/events/Definitions.events";
 export type { TaskStatus } from "./tasks_module/model/WfTask.model";
 export {
   IWorkflowDefinitions,
@@ -21,27 +23,37 @@ export {
   type ProcessDetails,
   type ProcessListQuery,
   type ProcessSummary,
+  type SavedDraft,
+  type SaveDraftOptions,
   type UpdateProcess,
   type VersionDetails,
   type VersionSummary,
 } from "./definitions_module/services/IWorkflowDefinitions.service";
 export {
   IWorkflowRuntime,
+  type CancelInstance,
   type EmitOptions,
   type EmitResult,
   type HistoryEntry,
   type InstanceDetails,
   type InstanceListQuery,
   type InstanceSummary,
+  type RetryInstance,
   type StartInstance,
   type TokenDetails,
 } from "./runtime_module/services/IWorkflowRuntime.service";
 export {
+  WORKFLOW_INSTANCE_CANCELLED,
   WORKFLOW_INSTANCE_FINISHED,
+  WORKFLOW_INSTANCE_RETRIED,
+  WORKFLOW_INSTANCE_STARTED,
   WORKFLOW_INSTANCES_DELETED,
   WORKFLOW_TASK_REQUESTED,
   WORKFLOW_TOKEN_CLOSED,
+  type WorkflowInstanceCancelled,
   type WorkflowInstanceFinished,
+  type WorkflowInstanceRetried,
+  type WorkflowInstanceStarted,
   type WorkflowInstancesDeleted,
   type WorkflowTaskRequested,
   type WorkflowTokenClosed,
@@ -50,10 +62,9 @@ export { workflowRuntimeConfig } from "./runtime_module/config/Runtime.config";
 export type { HistoryType } from "./runtime_module/model/WfHistory.model";
 export type { InstanceStatus, StartedVia } from "./runtime_module/model/WfInstance.model";
 export type { TokenStatus } from "./runtime_module/model/WfToken.model";
-export { WorkflowAccess, DenyWorkflowAccess, type WorkflowAccessTarget, type WorkflowAction } from "./access/WorkflowAccess";
 export { WorkflowInputValidator, DefaultWorkflowInputValidator, type WorkflowInputContext } from "./contracts/WorkflowInputValidator";
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
-export type { WorkflowActor, WorkflowPage, WorkflowPaging } from "./contracts/types";
+export type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging, WorkflowRequest, WorkflowToolMetadata } from "./contracts/types";
 
 // Augment the declaring file, not the "../di" re-export: re-export targets
 // depend on program file order and silently stop merging in some projects.

package/core/workflow/internal/WorkflowEvents.ts

@@ -0,0 +1,23 @@
+import type { ServiceProvider } from "../../di";
+import { EventBus, type EventToken, type Logger } from "../../kernel";
+
+/**
+ * Publishes the events of the workflow services after their action is saved, in
+ * the scope of the action. A failing handler is logged: the action stands.
+ */
+export class WorkflowEvents {
+  constructor(
+    private readonly bus: EventBus,
+    /** Event handlers run in this scope. */
+    private readonly scope: ServiceProvider,
+    private readonly logger?: Logger,
+  ) {}
+
+  async publish<T>(event: EventToken<T>, payload: T): Promise<void> {
+    try {
+      await this.bus.publishScoped(this.scope, event, payload);
+    } catch (error) {
+      this.logger?.error("workflow event handler failed", { event: event.name, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+}

package/core/workflow/internal/http.ts

@@ -1,25 +1,29 @@
-import { ForbiddenError, UnauthorizedError, type HttpContext } from "../../http";
-import { WorkflowAccess, type WorkflowAccessTarget, type WorkflowAction } from "../access/WorkflowAccess";
-import type { WorkflowActor } from "../contracts/types";
+import { IAccess, type AccessObject, type SubjectAccess } from "../../access";
+import { ForbiddenError, type HttpContext } from "../../http";
+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";
 
-/**
- * Asks the application's {@link WorkflowAccess} who calls and whether the action
- * is allowed. Without a registered access every route answers 403.
- */
-export async function authorize(ctx: HttpContext, action: WorkflowAction, target: WorkflowAccessTarget = {}): Promise<WorkflowActor> {
-  const access = ctx.services.tryResolve(WorkflowAccess);
-  if (access === undefined) throw new ForbiddenError("Workflow HTTP is closed: register a WorkflowAccess implementation");
-  const actor = await access.actor(ctx);
-  if (actor === undefined) throw new UnauthorizedError();
-  if (!await access.can(ctx, action, target)) throw new ForbiddenError();
-  return actor;
+/** 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;
 }
 
-/** Whom the caller's tasks are addressed to, from the application's {@link WorkflowAccess}. */
-export async function assigneesOf(ctx: HttpContext, actor: WorkflowActor): Promise<readonly string[]> {
-  const access = ctx.services.tryResolve(WorkflowAccess);
-  return access === undefined ? [] : await access.assignees(ctx, actor);
+/**
+ * The caller of a route; 401 without a subject. With `permission` and `object`
+ * also checks the object the route's `can` could not know: 403 without the
+ * right. The actor's id is the first owner id, so that `{ own: true }` means
+ * the instances the subject started.
+ */
+export async function callerOf(ctx: HttpContext, permission?: string, object?: AccessObject): Promise<WorkflowCaller> {
+  const access = await ctx.services.resolve(IAccess).for(ctx);
+  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 }, request: { ip: ctx.clientIp ?? null, userAgent: ctx.header("user-agent") ?? null } };
 }
 
 /** A route parameter as a string. */
@@ -63,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/WorkflowRuntime.module.ts

@@ -1,6 +1,8 @@
+import { AccessModule } from "../../access";
 import { Module, scoped, singleton } from "../../di";
 import { DefaultWorkflowInputValidator, WorkflowInputValidator } from "../contracts/WorkflowInputValidator";
 import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
+import { runtimePermissions } from "./access/Runtime.permissions";
 import { WorkflowRetention } from "./background/WorkflowRetention";
 import { WorkflowWorker } from "./background/WorkflowWorker";
 import { workflowRuntimeConfig } from "./config/Runtime.config";
@@ -21,7 +23,8 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
  * validator by registering its own `WorkflowInputValidator`.
  */
 @Module({
-  imports: [WorkflowDefinitionsModule],
+  imports: [AccessModule, WorkflowDefinitionsModule],
+  permissions: runtimePermissions,
   config: [workflowRuntimeConfig],
   ormBazis: { context: RuntimeDbContext, entities: [...RUNTIME_ENTITIES], ownedStore: runtimeStore, registerRepositories: false },
   providers: [

package/core/workflow/runtime_module/access/Runtime.permissions.ts

@@ -0,0 +1,28 @@
+import { definePermissions } from "../../../access";
+
+const process = { ref: "workflow.process", column: "processKey" };
+
+/** The rights of running processes (WORKFLOW-002 §6.2). */
+export const runtimePermissions = definePermissions({
+  "workflow.instances.start": {
+    title: { en: "Start processes", ru: "Запускать процессы" },
+    scope: "request",
+    on: { process },
+  },
+  "workflow.instances.read": {
+    title: { en: "See instances", ru: "Видеть экземпляры" },
+    scope: { column: "partition" },
+    on: { process },
+    owner: "startedById",
+  },
+  "workflow.instances.manage": {
+    title: { en: "Cancel and retry instances", ru: "Отменять и повторять экземпляры" },
+    scope: { column: "partition" },
+    on: { process },
+  },
+  "workflow.events.emit": {
+    title: { en: "Send events to processes", ru: "Отправлять события процессам" },
+    scope: "request",
+    on: { event: { type: "string" } },
+  },
+});

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

@@ -1,6 +1,7 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { Controller, Post, type HttpContext } from "../../../http";
-import { authorize, body, optionalString, param } from "../../internal/http";
+import { can } from "../../../access";
+import { Authorize, Controller, Post, type HttpContext } from "../../../http";
+import { body, callerOf, optionalString, param } from "../../internal/http";
 import { IWorkflowRuntime } from "../services/IWorkflowRuntime.service";
 
 /** Events from outside — a webhook, another service — over HTTP (WORKFLOW-001 §4). */
@@ -9,15 +10,17 @@ export class EventsController {
   constructor(private readonly runtime: IWorkflowRuntime) {}
 
   @Post(":eventKey")
+  @Authorize(can("workflow.events.emit"))
   async emit(ctx: HttpContext) {
     const eventKey = param(ctx, "eventKey");
     const request = await body(ctx);
     const partition = optionalString(request.partition, "partition") ?? null;
-    const actor = await authorize(ctx, "events.emit", { partition });
+    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,74 +1,90 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { Controller, Created, Get, Post, type HttpContext } from "../../../http";
-import { WorkflowError } from "../../contracts/WorkflowError";
-import { authorize, body, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import { can, type AccessObject } from "../../../access";
+import { Authorize, Controller, Created, Get, Post, type HttpContext } from "../../../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 } from "../services/IWorkflowRuntime.service";
+import { IWorkflowRuntime, type InstanceSummary } from "../services/IWorkflowRuntime.service";
 
-/** Instances over HTTP (WORKFLOW-001 §4); rights come from `WorkflowAccess` with the instance's partition. */
+/** Instances over HTTP (WORKFLOW-001 §4); rights are `workflow.instances.*` (WORKFLOW-002 §6.2). */
 @Controller("workflow/instances")
 export class InstancesController {
   constructor(private readonly runtime: IWorkflowRuntime) {}
 
   @Post()
+  @Authorize(can("workflow.instances.start"))
   async start(ctx: HttpContext) {
     const request = await body(ctx);
     const processKey = requiredString(request.processKey, "processKey", 64);
     const partition = optionalString(request.partition, "partition") ?? null;
-    const actor = await authorize(ctx, "instances.start", { processKey, partition });
+    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);
   }
 
   @Get()
+  @Authorize(can("workflow.instances.read"))
   async list(ctx: HttpContext) {
-    const partition = optionalString(ctx.query("partition"), "partition");
-    const processKey = optionalString(ctx.query("processKey"), "processKey");
-    await authorize(ctx, "instances.read", { partition: partition ?? null, ...(processKey === undefined ? {} : { processKey }) });
+    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),
-      partition,
-      processKey,
-      status: optionalString(ctx.query("status"), "status") as InstanceStatus | undefined,
-      businessKey: optionalString(ctx.query("businessKey"), "businessKey"),
-      startedById: optionalString(ctx.query("startedById"), "startedById"),
+      ...pagingOfList(list),
+      access: await access.filter("workflow.instances.read"),
+      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")
+  @Authorize(can("workflow.instances.read"))
   async get(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
-    await authorize(ctx, "instances.read", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
+    await callerOf(ctx, "workflow.instances.read", objectOf(instance));
     return instance;
   }
 
   @Get(":id/history")
+  @Authorize(can("workflow.instances.read"))
   async history(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
-    await authorize(ctx, "instances.read", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
+    await callerOf(ctx, "workflow.instances.read", objectOf(instance));
     return { data: await this.runtime.history(instance.id) };
   }
 
   @Post(":id/cancel")
+  @Authorize(can("workflow.instances.manage"))
   async cancel(ctx: HttpContext) {
     const instance = await this.runtime.instance(param(ctx, "id"));
     const request = await body(ctx);
-    const actor = await authorize(ctx, "instances.manage", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
-    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 authorize(ctx, "instances.manage", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
-    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);
 
+/** The instance as the object of a permission. */
+function objectOf(instance: InstanceSummary): AccessObject {
+  return { scope: instance.partition, process: instance.processKey, startedById: instance.startedBy.id };
+}
+

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,
       });