bazis 0.131.0 → 0.133.0

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,19 +81,19 @@ 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;
     }
-    const saved = instance.nodes[task.nodeId];
+    const saved = instance.tokens.find((t) => t.id === task.tokenId)?.output;
     await this.db.tasks.asNoTracking().where((t) => t.id.eq(task.id)).executeUpdate({
       status: "completed",
       completedById: actor.id,

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,25 @@
-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"
+  | "loop"
+  | "callProcess"
   | "timerCatch"
   | "eventWait"
   | "exclusiveGateway"
@@ -25,35 +31,26 @@ 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;
+  /** The `loop` whose body the node belongs to. */
+  readonly parent?: 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 +69,43 @@ 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 {
+  /** On whose behalf steps run: who started the instance (the default) or the process's own system actor. */
+  readonly runAs?: "starter" | "process";
+  /** How long the whole run may take, waits included: an ISO duration. */
+  readonly runTimeout?: string;
+  /** The default `timeout` of steps with a Tool: an ISO duration. */
+  readonly stepTimeout?: string;
+  /** How many instances of the process run at once; the rest wait as `pending`. */
+  readonly maxConcurrent?: number;
+  /** A new start with the `businessKey` of an unfinished instance: run as well, do not start, or wait for it. */
+  readonly sameKey?: "allow" | "skip" | "queue";
+  /** The key of the process to start when an instance fails or times out. */
+  readonly errorHandler?: 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 +119,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;
+}

package/library/workflow/expressionSyntax.ts

@@ -0,0 +1,243 @@
+import { expressionFunction, isExpressionNode, type Expr, type ExprFunctionName } from "./expressions";
+
+/** A text that is not an expression; `position` is the offset of the problem. */
+export class ExpressionSyntaxError extends Error {
+  override readonly name = "ExpressionSyntaxError";
+
+  constructor(message: string, readonly position: number) {
+    super(`${message} at ${position}`);
+  }
+}
+
+/** Binary operators by precedence; the same functions are also callable by name. */
+const LEVELS: readonly (readonly (readonly [symbol: string, op: ExprFunctionName])[])[] = [
+  [["or", "or"]],
+  [["and", "and"]],
+  [["==", "eq"], ["!=", "ne"], [">=", "gte"], ["<=", "lte"], [">", "gt"], ["<", "lt"]],
+  [["+", "add"], ["-", "sub"]],
+  [["*", "mul"], ["/", "div"], ["%", "mod"]],
+];
+
+const INFIX = new Map<string, { readonly symbol: string; readonly level: number }>(
+  LEVELS.flatMap((level, index) => level.map(([symbol, op]) => [op as string, { symbol, level: index }] as const)),
+);
+const UNARY_LEVEL = LEVELS.length;
+/** Comparisons do not chain: `a < b < c` means nothing, so they do not nest without brackets. */
+const NON_ASSOCIATIVE = 2;
+/** `{amount}` is `$vars.amount`; other roots are written in full: `{$input.orderId}`. */
+const VARIABLE_PREFIX = "$vars.";
+
+/**
+ * The designer's text of an expression (WORKFLOW-002 §3.8): `{amount} * 1.2`,
+ * `concat({a}, "-", {b})`, `now()`. One syntax for every designer. Lists and
+ * objects are JSON literals: their items are not expressions.
+ */
+export function parseExpression(text: string): Expr {
+  return new Parser(text).parse();
+}
+
+class Parser {
+  private position = 0;
+
+  constructor(private readonly text: string) {}
+
+  parse(): Expr {
+    const value = this.binary(0);
+    this.space();
+    if (this.position < this.text.length) this.fail(`unexpected ${JSON.stringify(this.text[this.position])}`);
+    return value;
+  }
+
+  private fail(message: string, position = this.position): never {
+    throw new ExpressionSyntaxError(message, position);
+  }
+
+  private space(): void {
+    while (/\s/.test(this.text[this.position] ?? "")) this.position += 1;
+  }
+
+  private binary(level: number): Expr {
+    if (level === LEVELS.length) return this.unary();
+    let left = this.binary(level + 1);
+    for (;;) {
+      const found = this.operator(level);
+      if (found === undefined) return left;
+      const right = this.binary(level + 1);
+      left = { op: found, args: [left, right] };
+      if (level === NON_ASSOCIATIVE && this.operator(level, false) !== undefined) this.fail("comparisons do not chain: use brackets");
+    }
+  }
+
+  private operator(level: number, take = true): ExprFunctionName | undefined {
+    this.space();
+    for (const [symbol, op] of LEVELS[level]!) {
+      if (!this.text.startsWith(symbol, this.position)) continue;
+      // A word operator must end: `order` is a name, not `or` and `der`.
+      if (/^[a-z]/.test(symbol) && /[A-Za-z0-9_]/.test(this.text[this.position + symbol.length] ?? "")) continue;
+      if (take) this.position += symbol.length;
+      return op;
+    }
+    return undefined;
+  }
+
+  private unary(): Expr {
+    this.space();
+    if (this.word("not")) return { op: "not", args: [this.unary()] };
+    if (this.text[this.position] === "-") {
+      const next = this.text[this.position + 1] ?? "";
+      if (/[0-9.]/.test(next)) return this.number();
+      this.position += 1;
+      return { op: "sub", args: [0, this.unary()] };
+    }
+    return this.primary();
+  }
+
+  private word(word: string): boolean {
+    if (!this.text.startsWith(word, this.position) || /[A-Za-z0-9_]/.test(this.text[this.position + word.length] ?? "")) return false;
+    // `not(a)` is the function call too, with the same meaning.
+    this.position += word.length;
+    return true;
+  }
+
+  private primary(): Expr {
+    this.space();
+    const char = this.text[this.position];
+    if (char === undefined) this.fail("the expression ends too early");
+    if (char === "(") {
+      this.position += 1;
+      const value = this.binary(0);
+      this.space();
+      if (this.text[this.position] !== ")") this.fail("expected )");
+      this.position += 1;
+      return value;
+    }
+    if (char === "\"") return this.string();
+    if (/[0-9.]/.test(char)) return this.number();
+    if (char === "[") return this.json("]");
+    if (char === "{") {
+      const after = /\s*(.)/.exec(this.text.slice(this.position + 1))?.[1];
+      return after === "\"" || after === "}" ? this.json("}") : this.path();
+    }
+    if (/[A-Za-z_]/.test(char)) return this.name();
+    return this.fail(`unexpected ${JSON.stringify(char)}`);
+  }
+
+  private path(): Expr {
+    const start = this.position;
+    const end = this.text.indexOf("}", start);
+    if (end < 0) this.fail("a path has no closing }", start);
+    const inner = this.text.slice(start + 1, end).trim();
+    if (!/^\$?[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(inner)) this.fail(`${JSON.stringify(inner)} is not a path`, start);
+    this.position = end + 1;
+    return { path: inner.startsWith("$") ? inner : `${VARIABLE_PREFIX}${inner}` };
+  }
+
+  private string(): string {
+    const start = this.position;
+    let at = start + 1;
+    while (at < this.text.length && this.text[at] !== "\"") at += this.text[at] === "\\" ? 2 : 1;
+    if (at >= this.text.length) this.fail("a string has no closing quote", start);
+    this.position = at + 1;
+    try {
+      return JSON.parse(this.text.slice(start, at + 1)) as string;
+    } catch {
+      return this.fail("the string has a bad escape", start);
+    }
+  }
+
+  private number(): number {
+    const match = /^-?(\d+(\.\d+)?|\.\d+)([eE][+-]?\d+)?/.exec(this.text.slice(this.position));
+    if (!match) this.fail("a number was expected");
+    this.position += match[0].length;
+    return Number(match[0]);
+  }
+
+  /** A JSON list or object, scanned to its closing bracket. */
+  private json(close: "]" | "}"): Expr {
+    const start = this.position;
+    let depth = 0;
+    let at = start;
+    for (; at < this.text.length; at += 1) {
+      const char = this.text[at]!;
+      if (char === "\"") {
+        at += 1;
+        while (at < this.text.length && this.text[at] !== "\"") at += this.text[at] === "\\" ? 2 : 1;
+      } else if (char === "[" || char === "{") {
+        depth += 1;
+      } else if (char === "]" || char === "}") {
+        depth -= 1;
+        if (depth === 0) break;
+      }
+    }
+    if (at >= this.text.length || this.text[at] !== close) this.fail(`expected ${close}`, start);
+    this.position = at + 1;
+    let value: unknown;
+    try {
+      value = JSON.parse(this.text.slice(start, at + 1));
+    } catch {
+      this.fail("a list or an object is JSON: its items are not expressions", start);
+    }
+    if (isExpressionNode(value)) this.fail("an object with op or path is not a literal", start);
+    return value as Expr;
+  }
+
+  private name(): Expr {
+    const start = this.position;
+    const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.text.slice(start))!;
+    const name = match[0];
+    this.position += name.length;
+    if (name === "true") return true;
+    if (name === "false") return false;
+    if (name === "null") return null;
+    this.space();
+    if (this.text[this.position] !== "(") this.fail(`unknown word ${name}: a variable is written {${name}}`, start);
+    const definition = expressionFunction(name);
+    if (!definition) this.fail(`unknown function ${name}`, start);
+    this.position += 1;
+    const args: Expr[] = [];
+    this.space();
+    if (this.text[this.position] === ")") {
+      this.position += 1;
+      return { op: definition.name, args };
+    }
+    for (;;) {
+      args.push(this.binary(0));
+      this.space();
+      const char = this.text[this.position];
+      this.position += 1;
+      if (char === ")") return { op: definition.name, args };
+      if (char !== ",") this.fail("expected , or )", this.position - 1);
+    }
+  }
+}
+
+/**
+ * The text of an expression: `parseExpression(printExpression(e))` gives `e`
+ * back. A call goes infix only with two arguments: `add(a, b, c)` stays a call,
+ * because `a + b + c` reads as two calls.
+ */
+export function printExpression(expression: Expr): string {
+  return print(expression, 0);
+}
+
+function print(expression: Expr, outer: number): string {
+  if (!isExpressionNode(expression)) return JSON.stringify(expression) ?? "null";
+  if ("path" in expression) {
+    const path = String(expression.path);
+    return `{${path.startsWith(VARIABLE_PREFIX) ? path.slice(VARIABLE_PREFIX.length) : path}}`;
+  }
+  const { op, args } = expression;
+  const infix = INFIX.get(op);
+  if (infix && args.length === 2) {
+    const { level, symbol } = infix;
+    // The right side binds one level tighter: `a - (b - c)` keeps its brackets. Comparisons do not chain at all.
+    const leftLevel = level === NON_ASSOCIATIVE ? level + 1 : level;
+    const text = `${print(args[0]!, leftLevel)} ${symbol} ${print(args[1]!, level + 1)}`;
+    return level < outer ? `(${text})` : text;
+  }
+  if (op === "not" && args.length === 1) {
+    const text = `not ${print(args[0]!, UNARY_LEVEL)}`;
+    return UNARY_LEVEL < outer ? `(${text})` : text;
+  }
+  return `${op}(${args.map((arg) => print(arg, 0)).join(", ")})`;
+}