bazis 0.131.0 → 0.132.0

package/core/workflow/runtime_module/model/WfInstance.model.ts

@@ -7,13 +7,14 @@ export type StartedVia = "manual" | "event" | "schedule";
 
 /**
  * One run of a process. Bound to the version it started with: a new publication
- * does not touch it. Its data: the input, the variables `saveTo` writes and the
- * result of each step by node id.
+ * does not touch it. Its data: the input, the variables and the result of each
+ * step by node id.
  */
 @Index(["partition", "status"])
 @Index(["processKey", "status"])
 @Index(["status", "endedAt"])
-@Entity({ table: "bazis_wf_run_instances" })
+@Index(["test", "createdAt"])
+@Entity({ table: "bazis_wf2_run_instances" })
 export class WfInstance {
   @UUID({ version: "v7" })
   id = "";
@@ -45,6 +46,30 @@ export class WfInstance {
   @Column({ type: "json" })
   nodes: Record<string, unknown> = {};
 
+  /** What the process gave back: its `out` variables when it completed. */
+  @Column({ type: "json", nullable: true })
+  output: Record<string, unknown> | null = null;
+
+  /** `$event`: the data of the event that started or last continued it. */
+  @Column({ type: "json", nullable: true })
+  event: unknown = null;
+
+  /** `$trigger`: how it was started. */
+  @Column({ type: "json", nullable: true })
+  trigger: Record<string, unknown> | null = null;
+
+  /** A trial run (WORKFLOW-002 §5.4, stage 5). */
+  @Column({ type: "boolean" })
+  test = false;
+
+  /** The instance whose `callProcess` started this one (stage 3). */
+  @Index()
+  @Column({ type: "text", nullable: true })
+  parentInstanceId: string | null = null;
+
+  @Column({ type: "text", nullable: true })
+  parentTokenId: string | null = null;
+
   @Index()
   @Column({ type: "text", nullable: true })
   businessKey: string | null = null;

package/core/workflow/runtime_module/model/WfJob.model.ts

@@ -9,7 +9,7 @@ export type JobKind = "tool" | "timer" | "retry" | "schedule";
  * token. Application instances claim it with `FOR UPDATE SKIP LOCKED`.
  */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
-@Entity({ table: "bazis_wf_run_jobs" })
+@Entity({ table: "bazis_wf2_run_jobs" })
 export class WfJob {
   @UUID({ version: "v7" })
   id = "";
@@ -34,6 +34,22 @@ export class WfJob {
   @Column({ type: "datetime" })
   dueAt = new Date(0);
 
+  /** What a job carries besides its token: an event to deliver (stage 4). */
+  @Column({ type: "json", nullable: true })
+  payload: unknown = null;
+
+  /** Jobs with one key merge into the last: `debounce` of an event start (stage 4). */
+  @Index()
+  @Column({ type: "text", nullable: true })
+  dedupeKey: string | null = null;
+
+  /** The partition and the start node of a `schedule` job (stage 4). */
+  @Column({ type: "text", nullable: true })
+  partition: string | null = null;
+
+  @Column({ type: "text", nullable: true })
+  nodeId: string | null = null;
+
   @Column({ type: "integer" })
   attempts = 0;
 

package/core/workflow/runtime_module/model/WfSubscription.model.ts

@@ -4,7 +4,7 @@ import { WfInstance } from "./WfInstance.model";
 /** A token waiting for an event: `eventWait` or `boundaryEvent`. Matched by key and correlation. */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
 @Index(["eventKey", "correlation"])
-@Entity({ table: "bazis_wf_run_subscriptions" })
+@Entity({ table: "bazis_wf2_run_subscriptions" })
 export class WfSubscription {
   @UUID({ version: "v7" })
   id = "";

package/core/workflow/runtime_module/model/WfToken.model.ts

@@ -10,7 +10,7 @@ export type TokenStatus = "active" | "waiting" | "done" | "cancelled" | "failed"
 /** Where execution is. After a parallel gateway an instance has several. Its id is the idempotency key of a Tool call. */
 @ForeignKey(() => WfInstance, { properties: ["instanceId"], onDelete: "cascade" })
 @Index(["instanceId", "status"])
-@Entity({ table: "bazis_wf_run_tokens" })
+@Entity({ table: "bazis_wf2_run_tokens" })
 export class WfToken {
   @UUID({ version: "v7" })
   id = "";
@@ -31,6 +31,16 @@ export class WfToken {
   @Column({ type: "json", nullable: true })
   output: unknown = null;
 
+  /** The loop token this one runs inside, with its iteration and what only the body sees (stage 3). */
+  @Column({ type: "text", nullable: true })
+  parentTokenId: string | null = null;
+
+  @Column({ type: "integer", nullable: true })
+  iteration: number | null = null;
+
+  @Column({ type: "json", nullable: true })
+  locals: Record<string, unknown> | null = null;
+
   @Column({ type: "createdAt" })
   createdAt = new Date(0);
 

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

@@ -13,6 +13,8 @@ export interface StartInstance extends WorkflowAuditOptions {
   readonly businessKey?: string | null;
   /** On whose behalf the steps run. */
   readonly actor: WorkflowActor;
+  /** The language of the request, for the application's validator; `workflow.language` by default. */
+  readonly language?: string;
 }
 
 export interface CancelInstance extends WorkflowAuditOptions {
@@ -52,6 +54,8 @@ export interface InstanceDetails extends InstanceSummary {
   readonly input: Record<string, unknown>;
   readonly vars: Record<string, unknown>;
   readonly nodes: Record<string, unknown>;
+  /** What the process gave back: its `out` variables; `null` until it completes. */
+  readonly output: Record<string, unknown> | null;
   /** Every token, oldest first. */
   readonly tokens: readonly TokenDetails[];
 }
@@ -105,7 +109,7 @@ export abstract class IWorkflowRuntime {
   /** Retries the failed steps of a `failed` instance. */
   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>;
+  abstract completeToken(tokenId: string, output: unknown, actor: WorkflowActor, options?: { readonly language?: string }): Promise<InstanceDetails>;
   /**
    * Delivers an event: starts processes whose latest version has an
    * `eventStart` for the key, and moves the instances waiting for it.

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

@@ -1,11 +1,12 @@
 import { grantsToWhere } from "../../../access";
 import { paginate } from "../../../orm";
-import type { FormIssue, FormSpec } from "../../../../library/workflow";
+import { inputSpecOf, type FormIssue, type FormSpec } from "../../../../library/workflow";
 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";
 import type { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { WorkflowEngine } from "../internal/WorkflowEngine";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfHistory } from "../model/WfHistory.model";
@@ -34,6 +35,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     private readonly definitions: IWorkflowDefinitions,
     /** The scope: the input validator is asked here, so that the application's own registration replaces the default. */
     private readonly services: ServiceProvider,
+    private readonly languages: WorkflowLanguages,
   ) {
     super();
   }
@@ -45,7 +47,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     const version = await this.definitions.latest(processKey);
     const start = Object.entries(version.document.nodes).find(([, node]) => node.kind === "manualStart");
     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 });
+    const { value, issues } = await this.validator().validate(inputSpecOf(version.document), options.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
     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, request: options.request ?? null });
     return await this.instance(id);
@@ -76,7 +78,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     return await this.instance(instanceId);
   }
 
-  async completeToken(tokenId: string, output: unknown, actor: WorkflowActor): Promise<InstanceDetails> {
+  async completeToken(tokenId: string, output: unknown, actor: WorkflowActor, options: { readonly language?: string } = {}): Promise<InstanceDetails> {
     actorOf(actor);
     if (!isUuid(tokenId)) throw new WorkflowError("not_found", `Token ${tokenId} does not exist`);
     const token = await this.db.tokens.asNoTracking().firstOrDefault((t) => t.id.eq(tokenId));
@@ -87,7 +89,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
       if (node?.kind !== "userTask" || !current || current.status !== "waiting" || step.instance.status !== "running") {
         throw new WorkflowError("wrong_status", "The token does not wait for a task");
       }
-      const { value, issues } = await this.validator().validate(node.config?.form as FormSpec | undefined, output, { purpose: "task", processKey: step.instance.processKey, partition: step.instance.partition });
+      const { value, issues } = await this.validator().validate(node.config?.form as FormSpec | undefined, output, { purpose: "task", processKey: step.instance.processKey, partition: step.instance.partition, language: options.language ?? this.languages.default, actor });
       if (issues.length > 0) throw new WorkflowError("invalid_input", "The task form is invalid", issues);
       await this.engine.complete(step, tokenId, value, actor);
       return true;
@@ -123,13 +125,13 @@ export class WorkflowRuntime extends IWorkflowRuntime {
       for (const [nodeId, node] of Object.entries(version.document.nodes)) {
         if (node.kind !== "eventStart" || node.config?.event !== eventKey) continue;
         // An event carries more than a process needs: fields the input does not declare are dropped, not refused.
-        const { value, issues: all } = await this.validator().validate(version.document.input, data, { purpose: "input", processKey: version.key, partition });
+        const { value, issues: all } = await this.validator().validate(inputSpecOf(version.document), data, { purpose: "input", processKey: version.key, partition, language: this.languages.default, actor });
         const issues = all.filter((issue) => issue.code !== "unknown");
         if (issues.length > 0) {
           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, request: options.request ?? null }));
+        started.push(await this.engine.begin(this.engine.cache(version), nodeId, { input: value, partition, businessKey: correlation, startedVia: "event", actor, request: options.request ?? null, event: { key: eventKey, payload: data } }));
       }
     }
     return { started, continued: [...continued], rejected };
@@ -155,7 +157,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     const row = await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(instanceId));
     if (!row) throw notFound(instanceId);
     const tokens = await this.db.tokens.asNoTracking().where((t) => t.instanceId.eq(instanceId)).orderBy((t) => t.id).toList();
-    return { ...summaryOf(row), input: row.input, vars: row.vars, nodes: row.nodes, tokens: tokens.map(tokenOf) };
+    return { ...summaryOf(row), input: row.input, vars: row.vars, nodes: row.nodes, output: row.output, tokens: tokens.map(tokenOf) };
   }
 
   async history(instanceId: string): Promise<readonly HistoryEntry[]> {

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

@@ -4,7 +4,7 @@ import { Authorize, Controller, Get, Post, type HttpContext } from "../../../htt
 import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import { buildListDocument } from "../../../../library/jsonapi";
-import { body, callerOf, filterOf, listQuery, pagingOfList, param } from "../../internal/http";
+import { body, callerOf, defaultLanguage, filterOf, listQuery, pagingOfList, param, withTitleText } from "../../internal/http";
 import type { TaskStatus } from "../model/WfTask.model";
 import { IWorkflowTasks, type TaskDetails } from "../services/IWorkflowTasks.service";
 
@@ -20,7 +20,7 @@ export class TasksController {
   @Get()
   @Authorize(can("workflow.tasks.work"))
   async list(ctx: HttpContext) {
-    const { access, actor } = await callerOf(ctx);
+    const { access, actor, language } = 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");
@@ -35,44 +35,45 @@ export class TasksController {
       partition,
       processKey: filterOf(list, "processKey"),
     });
-    return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
+    return buildListDocument(page.items.map((item) => withTitleText(item, language, defaultLanguage(ctx))), list, page.total, { basePath: ctx.path });
   }
 
   @Get(":id")
   @Authorize(can("workflow.tasks.work"))
   async get(ctx: HttpContext) {
-    return (await this.visible(ctx)).task;
+    const { task, language } = await this.visible(ctx);
+    return withTitleText(task, language, defaultLanguage(ctx));
   }
 
   @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);
+    const { task, actor, language } = await this.visible(ctx);
+    return withTitleText(await this.tasks.claim(task.id, actor), language, defaultLanguage(ctx));
   }
 
   @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);
+    const { task, actor, language } = await this.visible(ctx);
+    return withTitleText(await this.tasks.release(task.id, actor), language, defaultLanguage(ctx));
   }
 
   @Post(":id/complete")
   @Authorize(can("workflow.tasks.work"))
   async complete(ctx: HttpContext) {
-    const { task, actor, request: from } = await this.visible(ctx);
+    const { task, actor, request: from, language } = await this.visible(ctx);
     const request = await body(ctx);
-    return await this.tasks.complete(task.id, request.output ?? {}, actor, { request: from });
+    return withTitleText(await this.tasks.complete(task.id, request.output ?? {}, actor, { request: from, language }), language, defaultLanguage(ctx));
   }
 
   /** 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 }> {
+  private async visible(ctx: HttpContext): Promise<{ task: TaskDetails; actor: WorkflowActor; request: WorkflowRequest; language: string }> {
     const task = await this.tasks.get(param(ctx, "id"));
-    const { access, actor, request } = await callerOf(ctx, "workflow.tasks.work", { scope: task.partition, process: task.processKey });
+    const { access, actor, request, language } = 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 };
+    return { task, actor, request, language };
   }
 }
 contextOnlyController(TasksController);

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

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

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

@@ -1,5 +1,5 @@
 import { Column, Entity, Index, UUID } from "../../../orm";
-import type { FormSpec } from "../../../../library/workflow";
+import type { FormSpec, LocalizedText } from "../../../../library/workflow";
 
 /** `open` waits for someone, `claimed` is taken by one person, `completed` and `cancelled` are done. */
 export type TaskStatus = "open" | "claimed" | "completed" | "cancelled";
@@ -10,7 +10,7 @@ export type TaskStatus = "open" | "claimed" | "completed" | "cancelled";
  */
 @Index(["assignee", "status"])
 @Index(["partition", "status"])
-@Entity({ table: "bazis_wf_task_items" })
+@Entity({ table: "bazis_wf2_task_items" })
 export class WfTask {
   @UUID({ version: "v7" })
   id = "";
@@ -33,8 +33,12 @@ export class WfTask {
   @Column({ type: "text", nullable: true })
   partition: string | null = null;
 
-  @Column({ type: "text" })
-  title = "";
+  @Column({ type: "json" })
+  title: LocalizedText = "";
+
+  /** The task of a trial run (WORKFLOW-002 §5.4, stage 5). */
+  @Column({ type: "boolean" })
+  test = false;
 
   /** `role:<code>` or `user:<id>`. */
   @Column({ type: "text" })

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

@@ -1,4 +1,4 @@
-import type { FormSpec } from "../../../../library/workflow";
+import type { FormSpec, LocalizedText } from "../../../../library/workflow";
 import type { AccessFilter, ScopePrincipals } from "../../../access";
 import type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging } from "../../contracts/types";
 import type { TaskStatus } from "../model/WfTask.model";
@@ -10,7 +10,7 @@ export interface TaskDetails {
   readonly processKey: string;
   readonly nodeId: string;
   readonly partition: string | null;
-  readonly title: string;
+  readonly title: LocalizedText;
   readonly assignee: string;
   readonly form: FormSpec | null;
   readonly dueAt: Date | null;
@@ -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, options?: WorkflowAuditOptions): Promise<TaskDetails>;
+  abstract complete(taskId: string, output: unknown, actor: WorkflowActor, options?: WorkflowAuditOptions & { readonly language?: string }): Promise<TaskDetails>;
 }

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

@@ -47,7 +47,7 @@ export class WorkflowTasks extends IWorkflowTasks {
 
   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);
+    const rows = await this.db.database.querySqlRaw(`SELECT DISTINCT "partition" FROM "bazis_wf2_task_items" WHERE "status" IN (${statuses.map((_, index) => `{${index}}`).join(", ")})`, ...statuses);
     return rows.map((row) => row.partition as string | null);
   }
 
@@ -81,14 +81,14 @@ export class WorkflowTasks extends IWorkflowTasks {
     });
   }
 
-  async complete(taskId: string, output: unknown, actor: WorkflowActor, options: WorkflowAuditOptions = {}): Promise<TaskDetails> {
+  async complete(taskId: string, output: unknown, actor: WorkflowActor, options: WorkflowAuditOptions & { readonly language?: string } = {}): 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}`);
     let instance;
     try {
       // The form is checked and the process moves on first; the task follows.
-      instance = await this.runtime.completeToken(task.tokenId, output, actor);
+      instance = await this.runtime.completeToken(task.tokenId, output, actor, options.language === undefined ? {} : { language: options.language });
     } catch (error) {
       if (error instanceof WorkflowError && error.code === "wrong_status") await this.close(task.tokenId, "cancelled");
       throw error;

package/library/openapi/codegen.ts

@@ -695,6 +695,9 @@ function applyValidatorOptions(schema: OpenApiCodegenSchema, options: Record<str
   if (typeof options.refScope === "string") {
     out["x-ref-scope"] = options.refScope;
   }
+  if (options.personal === true) {
+    out["x-personal"] = true;
+  }
   return out;
 }
 

package/library/validation/types/ValidatorOptions.ts

@@ -160,4 +160,6 @@ export interface ValidatorOptions {
   refKeys?: string;
   /** JSON Pointer to the sibling input that sets their area (`x-ref-scope`): `/table`. */
   refScope?: `/${string}`;
+  /** Personal data (`x-personal`): a process masks the value in its history. */
+  personal?: boolean;
 }

package/library/workflow/ProcessDocument.ts

@@ -1,19 +1,23 @@
-import type { FormSpec } from "./formFields";
+import type { Expr } from "./expressions";
+import type { VariableSpec } from "./formFields";
+import type { LocalizedText } from "./localized";
 
 /**
  * A process document: the framework's own JSON, not BPMN XML (a designer may
- * render BPMN from it). One object holds the process input (`input`), the graph
- * (`nodes`, `flows`) and the canvas layout (`diagram`).
+ * render BPMN from it). One object holds the variables, the settings, the graph
+ * (`nodes`, `flows`), the canvas layout (`diagram`) and the application's data
+ * (`extensions`).
  */
-export const PROCESS_SCHEMA_VERSION = "bazis.workflow/v1";
+export const PROCESS_SCHEMA_VERSION = "bazis.workflow/v2";
 
-/** The node kinds of version 1; closed: a new kind comes with a new document version. */
+/** The node kinds of version 2; closed: a new kind comes with a new document version. */
 export type NodeKind =
   | "manualStart"
   | "scheduleStart"
   | "eventStart"
   | "userTask"
   | "serviceTask"
+  | "assign"
   | "timerCatch"
   | "eventWait"
   | "exclusiveGateway"
@@ -25,35 +29,24 @@ export type NodeKind =
 
 export interface ProcessNode {
   readonly kind: NodeKind;
-  readonly title: string;
+  readonly title: LocalizedText;
   /** Boundary nodes only: the step the node is attached to. */
   readonly attachedTo?: string;
   readonly config?: Readonly<Record<string, unknown>>;
+  /** The application's data by namespace; the engine does not read it. */
+  readonly extensions?: Readonly<Record<string, unknown>>;
 }
 
 export interface ProcessFlow {
   readonly source: string;
   readonly target: string;
-  readonly title?: string;
+  readonly title?: LocalizedText;
   /** Condition of a flow that leaves an exclusive gateway. */
-  readonly condition?: Condition;
+  readonly condition?: Expr;
   /** The flow an exclusive gateway takes when no condition holds. */
   readonly isDefault?: boolean;
 }
 
-/** Comparison operators of conditions. */
-export type ConditionOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "contains" | "empty" | "notEmpty";
-
-/**
- * A condition: a tree of `all` / `any` / `not` and comparisons. `path` addresses
- * instance data: `$input.<field>`, `$vars.<name>`, `$nodes.<node>.<field>`.
- */
-export type Condition =
-  | { readonly all: readonly Condition[] }
-  | { readonly any: readonly Condition[] }
-  | { readonly not: Condition }
-  | { readonly path: string; readonly op: ConditionOp; readonly value?: unknown };
-
 export interface Bounds {
   readonly x: number;
   readonly y: number;
@@ -72,13 +65,33 @@ export interface ProcessDiagram {
   readonly edges: Readonly<Record<string, { readonly waypoints: readonly Point[] }>>;
 }
 
+/** What goes to the history of an instance. */
+export interface ProcessLogSettings {
+  /** The values of variables an `assign` step sets; `false` by default. */
+  readonly variables?: boolean;
+  /** The input and output of Tools; `false` by default. */
+  readonly toolPayloads?: boolean;
+  /** Personal data shows as `***`; `true` by default. */
+  readonly maskPersonal?: boolean;
+}
+
+/** Settings of a process: they are part of the version. */
+export interface ProcessSettings {
+  /** The default `timeout` of steps with a Tool: an ISO duration. */
+  readonly stepTimeout?: string;
+  readonly log?: ProcessLogSettings;
+}
+
 export interface ProcessDocument {
   readonly schemaVersion: typeof PROCESS_SCHEMA_VERSION;
-  /** Fields the process starts with; without them it starts with no data. */
-  readonly input?: FormSpec;
+  /** `in` — the input of a start, `local` — inside the process, `out` — what it gives back. */
+  readonly variables?: readonly VariableSpec[];
+  readonly settings?: ProcessSettings;
   readonly nodes: Readonly<Record<string, ProcessNode>>;
   readonly flows: Readonly<Record<string, ProcessFlow>>;
   readonly diagram?: ProcessDiagram;
+  /** The application's data by namespace; the engine does not read it. */
+  readonly extensions?: Readonly<Record<string, unknown>>;
 }
 
 /** A new process: a manual start leading straight to the end. It already passes validation. */
@@ -92,3 +105,26 @@ export function emptyProcess(): ProcessDocument {
     flows: { StartToEnd: { source: "Start", target: "End" } },
   };
 }
+
+/** The fields a start takes: the `in` variables. */
+export function inputSpecOf(document: Pick<ProcessDocument, "variables">): { readonly fields: readonly VariableSpec[] } {
+  return { fields: (document.variables ?? []).filter((variable) => variable.direction === "in") };
+}
+
+/** What `$vars` holds at the start: the `local` and `out` variables with a default. */
+export function initialVarsOf(document: Pick<ProcessDocument, "variables">): Record<string, unknown> {
+  const vars: Record<string, unknown> = {};
+  for (const variable of document.variables ?? []) {
+    if (variable.direction !== "in" && variable.default !== undefined) vars[variable.name] = variable.default;
+  }
+  return vars;
+}
+
+/** What a finished process gives back: its `out` variables. */
+export function outputOf(document: Pick<ProcessDocument, "variables">, vars: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+  for (const variable of document.variables ?? []) {
+    if (variable.direction === "out") output[variable.name] = Object.hasOwn(vars, variable.name) ? vars[variable.name] : null;
+  }
+  return output;
+}