bazis 0.131.0 → 0.133.0

package/library/workflow/localized.ts

@@ -0,0 +1,35 @@
+/** A text in several languages: language → text. A plain string is in the default language. */
+export type LocalizedText = string | Readonly<Record<string, string>>;
+
+const LANGUAGE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+/** The text for `language`: its exact entry, its base language (`ru` for `ru-RU`), then `fallback`, then the first one. */
+export function textOf(text: LocalizedText | null | undefined, language: string, fallback = language): string {
+  if (text === undefined || text === null) return "";
+  if (typeof text === "string") return text;
+  const own = (key: string) => (Object.hasOwn(text, key) ? text[key] : undefined);
+  return own(language) ?? own(language.split("-")[0]!) ?? own(fallback) ?? Object.values(text)[0] ?? "";
+}
+
+/** Every text of a value, the default language first: what a search looks through and a list sorts by. */
+export function allTexts(text: LocalizedText | null | undefined, language: string): string {
+  if (text === undefined || text === null) return "";
+  if (typeof text === "string") return text;
+  const first = textOf(text, language);
+  return [first, ...Object.values(text).filter((item) => item !== first)].join("\n");
+}
+
+/** What is wrong with a value as a localized text, or `null`. `min` — 1 for a required text. */
+export function checkLocalizedText(value: unknown, max: number, min = 1): string | null {
+  const fits = (text: unknown) => typeof text === "string" && text.trim().length >= min && text.length <= max;
+  const size = min === 0 ? `up to ${max}` : `${min}–${max}`;
+  if (typeof value === "string") return fits(value) ? null : `must be ${size} characters`;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return "must be a string or an object of language → text";
+  const entries = Object.entries(value);
+  if (entries.length === 0) return "needs at least one language";
+  for (const [language, text] of entries) {
+    if (!LANGUAGE.test(language)) return `has an invalid language ${JSON.stringify(language)}`;
+    if (!fits(text)) return `${language} must be ${size} characters`;
+  }
+  return null;
+}

package/library/workflow/masking.ts

@@ -0,0 +1,72 @@
+import { isExpressionNode } from "./expressions";
+import { isPath } from "./paths";
+import type { ProcessDocument } from "./ProcessDocument";
+
+/** What a personal value shows as in the history. */
+export const PERSONAL_MASK = "***";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Whether personal data is masked in the history of this version: yes unless `log.maskPersonal` is `false`. */
+export function masksPersonal(document: Pick<ProcessDocument, "settings">): boolean {
+  return document.settings?.log?.maskPersonal !== false;
+}
+
+/**
+ * The paths of the personal variables: `$input.email`, `$vars.email`. A loop over
+ * personal data adds its element: `$item` and the name the loop gives it.
+ */
+export function personalPaths(document: Pick<ProcessDocument, "variables"> & Partial<Pick<ProcessDocument, "nodes">>): ReadonlySet<string> {
+  const paths = new Set((document.variables ?? []).filter((variable) => variable.personal === true).map((variable) => `${variable.direction === "in" ? "$input" : "$vars"}.${variable.name}`));
+  const loops = Object.values(document.nodes ?? {}).filter((node) => node.kind === "loop" && node.config?.over !== undefined);
+  // A loop over the element of another loop: as many passes as it takes.
+  for (let size = -1; size !== paths.size;) {
+    size = paths.size;
+    for (const { config } of loops) {
+      if (!readsPersonal(config!.over, paths)) continue;
+      paths.add("$item");
+      if (typeof config!.item === "string") paths.add(`$vars.${config!.item}`);
+    }
+  }
+  return paths;
+}
+
+/** The names of the personal `local` and `out` variables. */
+export function personalVariables(document: Pick<ProcessDocument, "variables">): ReadonlySet<string> {
+  return new Set((document.variables ?? []).filter((variable) => variable.personal === true && variable.direction !== "in").map((variable) => variable.name));
+}
+
+function touches(path: string, personal: ReadonlySet<string>): boolean {
+  for (const root of personal) if (path === root || path.startsWith(`${root}.`)) return true;
+  return false;
+}
+
+/** Whether an expression or a path string reads a personal variable. */
+export function readsPersonal(value: unknown, personal: ReadonlySet<string>): boolean {
+  if (isPath(value)) return touches(value, personal);
+  if (!isExpressionNode(value)) return false;
+  if ("path" in value) return typeof value.path === "string" && touches(value.path, personal);
+  return Array.isArray(value.args) && value.args.some((arg) => readsPersonal(arg, personal));
+}
+
+/** A resolved step input with what its mapping took from personal variables masked. */
+export function maskByMapping(mapping: unknown, value: unknown, personal: ReadonlySet<string>): unknown {
+  if (personal.size === 0) return value;
+  if (readsPersonal(mapping, personal)) return PERSONAL_MASK;
+  if (isExpressionNode(mapping)) return value;
+  if (Array.isArray(mapping) && Array.isArray(value)) return value.map((item, index) => maskByMapping(mapping[index], item, personal));
+  if (isObject(mapping) && isObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskByMapping(mapping[key], item, personal)]));
+  return value;
+}
+
+/** A value with the fields its JSON Schema marks `x-personal` masked. */
+export function maskBySchema(value: unknown, schema: unknown): unknown {
+  if (!isObject(schema) || value === null || value === undefined) return value;
+  if (schema["x-personal"] === true) return PERSONAL_MASK;
+  if (Array.isArray(value)) return value.map((item) => maskBySchema(item, schema.items));
+  if (!isObject(value) || !isObject(schema.properties)) return value;
+  const properties = schema.properties;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, Object.hasOwn(properties, key) ? maskBySchema(item, properties[key]) : item]));
+}

package/library/workflow/mermaid.ts

@@ -1,4 +1,7 @@
-import type { Condition, NodeKind, ProcessDocument } from "./ProcessDocument";
+import type { Expr } from "./expressions";
+import { printExpression } from "./expressionSyntax";
+import { textOf } from "./localized";
+import type { NodeKind, ProcessDocument } from "./ProcessDocument";
 
 /** Words Mermaid reads as syntax: such node ids are renamed. */
 const RESERVED = new Set(["end", "graph", "flowchart", "subgraph", "style", "class", "classdef", "click", "default", "linkstyle", "direction"]);
@@ -10,6 +13,9 @@ const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
   end: ["((", "))"],
   userTask: ["[", "]"],
   serviceTask: ["[[", "]]"],
+  callProcess: ["[[", "]]"],
+  loop: ["[", "]"],
+  assign: ["[/", "/]"],
   timerCatch: ["{{", "}}"],
   eventWait: ["{{", "}}"],
   exclusiveGateway: ["{", "}"],
@@ -21,7 +27,7 @@ const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
 
 /**
  * A process as a Mermaid `flowchart` (WORKFLOW-001 §14): starts are stadiums,
- * Tool steps subroutines, tasks rectangles, waits hexagons, gateways rhombi,
+ * Tool steps and called processes subroutines, a loop a subgraph around its body, tasks rectangles, waits hexagons, gateways rhombi,
  * ends and boundary events circles. A boundary event hangs on its step by a
  * dotted link. Labels show the node kind's detail: the Tool, the cron, the
  * duration, the event key; flows show their title or condition.
@@ -39,17 +45,29 @@ export function processToMermaid(document: ProcessDocument, direction: "LR" | "T
     return id;
   };
   const lines = [`flowchart ${direction}`];
-  for (const [nodeId, node] of Object.entries(document.nodes)) {
-    const [open, close] = SHAPES[node.kind] ?? ["[", "]"];
-    const detail = detailOf(node.kind, node.config ?? {});
-    lines.push(`  ${idOf(nodeId)}${open}"${label(node.title || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}"${close}`);
-  }
+  // A loop is a subgraph around its body; flows and boundaries link to it by its id.
+  const write = (parent: string | undefined, indent: string): void => {
+    for (const [nodeId, node] of Object.entries(document.nodes)) {
+      if (node.parent !== parent) continue;
+      const detail = detailOf(node.kind, node.config ?? {});
+      const text = `${label(textOf(node.title, "en") || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}`;
+      if (node.kind === "loop") {
+        lines.push(`${indent}subgraph ${idOf(nodeId)}["${text}"]`);
+        write(nodeId, `${indent}  `);
+        lines.push(`${indent}end`);
+        continue;
+      }
+      const [open, close] = SHAPES[node.kind] ?? ["[", "]"];
+      lines.push(`${indent}${idOf(nodeId)}${open}"${text}"${close}`);
+    }
+  };
+  write(undefined, "  ");
   for (const [nodeId, node] of Object.entries(document.nodes)) {
     if (node.attachedTo !== undefined && document.nodes[node.attachedTo] !== undefined) lines.push(`  ${idOf(node.attachedTo)} -.- ${idOf(nodeId)}`);
   }
   for (const flow of Object.values(document.flows)) {
     if (document.nodes[flow.source] === undefined || document.nodes[flow.target] === undefined) continue;
-    const text = flow.title ?? (flow.condition !== undefined ? conditionText(flow.condition) : flow.isDefault === true ? "default" : undefined);
+    const text = flow.title !== undefined ? textOf(flow.title, "en") : flow.condition !== undefined ? expressionText(flow.condition) : flow.isDefault === true ? "default" : undefined;
     lines.push(`  ${idOf(flow.source)} -->${text === undefined ? "" : `|"${label(text)}"|`} ${idOf(flow.target)}`);
   }
   return `${lines.join("\n")}\n`;
@@ -59,6 +77,8 @@ function detailOf(kind: NodeKind, config: Readonly<Record<string, unknown>>): st
   const text = (value: unknown) => (typeof value === "string" && value !== "" ? value : undefined);
   switch (kind) {
     case "serviceTask": return text(config.tool);
+    case "callProcess": return text(config.process);
+    case "loop": return typeof config.times === "number" ? `${config.times} times` : config.while !== undefined ? "while" : "for each";
     case "scheduleStart": return text(config.cron);
     case "eventStart":
     case "eventWait":
@@ -70,15 +90,21 @@ function detailOf(kind: NodeKind, config: Readonly<Record<string, unknown>>): st
       const assignee = config.assignee as { role?: unknown; user?: unknown } | undefined;
       return assignee === undefined ? undefined : text(assignee.role) !== undefined ? `role ${assignee.role}` : text(assignee.user) === undefined ? undefined : `user ${assignee.user}`;
     }
+    case "assign": {
+      const list = config.assignments;
+      return Array.isArray(list) ? list.map((item: { var?: unknown }) => String(item.var)).join(", ") : undefined;
+    }
     default: return undefined;
   }
 }
 
-function conditionText(condition: Condition): string {
-  if ("all" in condition) return condition.all.map(conditionText).join(" and ");
-  if ("any" in condition) return condition.any.map(conditionText).join(" or ");
-  if ("not" in condition) return `not (${conditionText(condition.not)})`;
-  return condition.op === "empty" || condition.op === "notEmpty" ? `${condition.path} ${condition.op}` : `${condition.path} ${condition.op} ${JSON.stringify(condition.value)}`;
+/** A condition in the designer's syntax; one that does not print shows as JSON. */
+function expressionText(expression: Expr): string {
+  try {
+    return printExpression(expression);
+  } catch {
+    return JSON.stringify(expression);
+  }
 }
 
 /** Text inside a quoted Mermaid label: quotes and markup are entities. */

package/library/workflow/nodeKinds.ts

@@ -1,24 +1,37 @@
 import { parseCron } from "./cron";
-import { checkFormSpec } from "./formFields";
+import { FIELD_NAME, checkFormSpec } from "./formFields";
 import { DATA_PATH } from "./paths";
 import type { NodeKind } from "./ProcessDocument";
 
 /** The role of a node in the graph: it sets the rules of incoming and outgoing flows. */
 export type NodeRole = "start" | "activity" | "gateway" | "boundary" | "end";
 
+/** A JSON Schema, as the palette gives it to a designer. */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+
 export interface NodeKindDefinition {
   readonly kind: NodeKind;
   readonly role: NodeRole;
+  /** A container: other nodes name it as their `parent`. */
+  readonly container?: boolean;
   /** Checks the node `config`; returns a problem or `null`. */
   readonly check: (config: Record<string, unknown>) => string | null;
+  /** The node `config` as a JSON Schema: what a designer builds the form of a step from. */
+  readonly config: JsonSchema;
 }
 
 /** ISO 8601 duration without months and years: P1D, PT2H30M, PT45S. */
 export const ISO_DURATION = /^P(?!$)(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
 /** An event key or a Tool name: `payments.received`, `payments.charge`. */
 export const DOTTED_KEY = /^[a-z][a-z0-9_-]*(\.[a-z][a-z0-9_-]*)+$/;
-/** A process variable name. */
-export const VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/** A process key. */
+export const PROCESS_KEY = /^[a-z][a-z0-9_.-]{0,63}$/;
+/** The most iterations a loop may have. */
+export const MAX_ITERATIONS = 10_000;
+/** The most iterations of a loop that run at once. */
+export const MAX_LOOP_PARALLEL = 100;
+/** A parameter of a Tool. */
+const PARAMETER = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
 const ROLE = /^[a-z][a-z0-9_.-]{0,63}$/;
 const USER = /^[^\s:][^\s]{0,127}$/;
 
@@ -74,7 +87,7 @@ function inputMapping(config: Record<string, unknown>): string | null {
   const value = config.input;
   if (value === undefined) return null;
   if (typeof value !== "object" || value === null || Array.isArray(value)) return "config.input must be an object";
-  return Object.keys(value).every((key) => VAR_NAME.test(key)) ? null : "config.input has an invalid parameter name";
+  return Object.keys(value).every((key) => PARAMETER.test(key)) ? null : "config.input has an invalid parameter name";
 }
 
 /** Automatic retries of a failed Tool call. */
@@ -84,23 +97,140 @@ function retry(config: Record<string, unknown>): string | null {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return "config.retry must be an object";
   const policy = value as Record<string, unknown>;
   if (!Number.isSafeInteger(policy.maxAttempts) || (policy.maxAttempts as number) < 1 || (policy.maxAttempts as number) > 10) return "config.retry.maxAttempts must be 1–10";
+  if (policy.growth !== undefined && policy.growth !== "fixed" && policy.growth !== "exponential") return "config.retry.growth must be fixed or exponential";
+  if (policy.factor !== undefined) {
+    if (policy.growth === "fixed") return "config.retry.factor is only for exponential growth";
+    if (typeof policy.factor !== "number" || !(policy.factor >= 1) || policy.factor > 100) return "config.retry.factor must be a number 1–100";
+  }
   return string(policy, "backoff", ISO_DURATION, false)?.replace("config.", "config.retry.") ?? null;
 }
 
+/** What a failed Tool step does when no error boundary takes it. */
+function onError(config: Record<string, unknown>): string | null {
+  return config.onError === undefined || config.onError === "fail" || config.onError === "skip" ? null : "config.onError must be fail or skip";
+}
+
+/** The shape of an `assign` step; its variables and expressions are checked with the whole document. */
+function assignments(config: Record<string, unknown>): string | null {
+  const list = config.assignments;
+  if (!Array.isArray(list) || list.length === 0) return "config.assignments must be a non-empty list";
+  for (const [index, item] of list.entries()) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) return `config.assignments[${index}] must be an object`;
+    const { var: name, value } = item as { var?: unknown; value?: unknown };
+    if (typeof name !== "string" || !FIELD_NAME.test(name)) return `config.assignments[${index}].var is invalid`;
+    if (value === undefined) return `config.assignments[${index}].value is required`;
+  }
+  return null;
+}
+
+/** What a loop runs over and how; its expressions are checked with the whole document. */
+function loop(config: Record<string, unknown>): string | null {
+  const sources = ["over", "while", "times"].filter((key) => config[key] !== undefined);
+  if (sources.length !== 1) return "config needs exactly one of over, while or times";
+  const { maxIterations, times, parallel, onItemError: onItem, collect } = config;
+  if (!Number.isSafeInteger(maxIterations) || (maxIterations as number) < 1 || (maxIterations as number) > MAX_ITERATIONS) return `config.maxIterations must be 1–${MAX_ITERATIONS}`;
+  if (times !== undefined && (!Number.isSafeInteger(times) || (times as number) < 1 || (times as number) > (maxIterations as number))) return "config.times must be an integer from 1 to maxIterations";
+  if (parallel !== undefined) {
+    if (typeof parallel !== "object" || parallel === null || Array.isArray(parallel)) return "config.parallel must be an object";
+    const { limit } = parallel as { limit?: unknown };
+    if (!Number.isSafeInteger(limit) || (limit as number) < 1 || (limit as number) > MAX_LOOP_PARALLEL) return `config.parallel.limit must be 1–${MAX_LOOP_PARALLEL}`;
+    if (config.while !== undefined) return "config.parallel does not go with while: its condition depends on the iteration before";
+  }
+  if (onItem !== undefined && onItem !== "stop" && onItem !== "skip") return "config.onItemError must be stop or skip";
+  if (collect !== undefined) {
+    if (typeof collect !== "object" || collect === null || Array.isArray(collect)) return "config.collect must be an object";
+    const { from, to } = collect as { from?: unknown; to?: unknown };
+    if (from === undefined) return "config.collect.from is required";
+    if (typeof to !== "string" || !FIELD_NAME.test(to)) return "config.collect.to is invalid";
+  }
+  return first(string(config, "item", FIELD_NAME, false), string(config, "index", FIELD_NAME, false));
+}
+
+const duration = { type: "string", format: "duration" };
+const text = { type: "string" };
+const dataPath = { type: "string", pattern: DATA_PATH.source };
+const saveTo = { type: "string", pattern: FIELD_NAME.source };
+const expression = { description: "An expression: a JSON literal, { path } or { op, args }" };
+const flag = { type: "boolean" };
+const object = (properties: Record<string, unknown>, required: readonly string[] = []): JsonSchema => ({ type: "object", properties, ...(required.length === 0 ? {} : { required }) });
+const timerConfig = { duration, at: dataPath };
+const fields = { type: "object", properties: { fields: { type: "array", items: { type: "object" } } }, required: ["fields"] };
+
 export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
-  { kind: "manualStart", role: "start", check: none },
-  { kind: "scheduleStart", role: "start", check: cron },
-  { kind: "eventStart", role: "start", check: (c) => string(c, "event", DOTTED_KEY) },
-  { kind: "userTask", role: "activity", check: (c) => first(assignee(c), form(c), string(c, "dueIn", ISO_DURATION, false)) },
-  { kind: "serviceTask", role: "activity", check: (c) => first(string(c, "tool", DOTTED_KEY), inputMapping(c), string(c, "saveTo", VAR_NAME, false), retry(c)) },
-  { kind: "timerCatch", role: "activity", check: timer },
-  { kind: "eventWait", role: "activity", check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), string(c, "saveTo", VAR_NAME, false)) },
-  { kind: "exclusiveGateway", role: "gateway", check: none },
-  { kind: "parallelGateway", role: "gateway", check: none },
-  { kind: "boundaryError", role: "boundary", check: (c) => string(c, "errorCode", /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, false) },
-  { kind: "boundaryTimer", role: "boundary", check: (c) => first(timer(c), boolean(c, "interrupting")) },
-  { kind: "boundaryEvent", role: "boundary", check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), boolean(c, "interrupting")) },
-  { kind: "end", role: "end", check: none },
+  { kind: "manualStart", role: "start", check: none, config: object({}) },
+  { kind: "scheduleStart", role: "start", check: cron, config: object({ cron: text }, ["cron"]) },
+  { kind: "eventStart", role: "start", check: (c) => string(c, "event", DOTTED_KEY), config: object({ event: text }, ["event"]) },
+  {
+    kind: "userTask",
+    role: "activity",
+    check: (c) => first(assignee(c), form(c), string(c, "dueIn", ISO_DURATION, false), string(c, "saveTo", FIELD_NAME, false)),
+    config: object({ assignee: object({ role: text, user: text }), form: fields, dueIn: duration, saveTo }, ["assignee"]),
+  },
+  {
+    kind: "serviceTask",
+    role: "activity",
+    check: (c) => first(string(c, "tool", DOTTED_KEY), inputMapping(c), string(c, "saveTo", FIELD_NAME, false), retry(c), string(c, "timeout", ISO_DURATION, false), onError(c)),
+    config: object({
+      tool: text,
+      input: { type: "object", description: "Parameter → a literal, a path string or an expression" },
+      saveTo,
+      timeout: duration,
+      retry: object({ maxAttempts: { type: "integer", minimum: 1, maximum: 10 }, backoff: duration, growth: { enum: ["fixed", "exponential"] }, factor: { type: "number", minimum: 1, maximum: 100 } }, ["maxAttempts"]),
+      onError: { enum: ["fail", "skip"] },
+    }, ["tool"]),
+  },
+  {
+    kind: "assign",
+    role: "activity",
+    check: assignments,
+    config: object({ assignments: { type: "array", minItems: 1, items: object({ var: { type: "string", pattern: FIELD_NAME.source }, value: expression }, ["var", "value"]) } }, ["assignments"]),
+  },
+  {
+    kind: "loop",
+    role: "activity",
+    container: true,
+    check: loop,
+    config: object({
+      over: expression,
+      while: expression,
+      times: { type: "integer", minimum: 1, maximum: MAX_ITERATIONS },
+      item: saveTo,
+      index: saveTo,
+      maxIterations: { type: "integer", minimum: 1, maximum: MAX_ITERATIONS },
+      parallel: object({ limit: { type: "integer", minimum: 1, maximum: MAX_LOOP_PARALLEL } }, ["limit"]),
+      onItemError: { enum: ["stop", "skip"] },
+      collect: object({ from: expression, to: saveTo }, ["from", "to"]),
+    }, ["maxIterations"]),
+  },
+  {
+    kind: "callProcess",
+    role: "activity",
+    check: (c) => first(string(c, "process", PROCESS_KEY), inputMapping(c), string(c, "saveTo", FIELD_NAME, false), onError(c)),
+    config: object({
+      process: { type: "string", pattern: PROCESS_KEY.source },
+      input: { type: "object", description: "Parameter → a literal, a path string or an expression" },
+      saveTo,
+      onError: { enum: ["fail", "skip"] },
+    }, ["process"]),
+  },
+  { kind: "timerCatch", role: "activity", check: timer, config: object(timerConfig) },
+  {
+    kind: "eventWait",
+    role: "activity",
+    check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), string(c, "saveTo", FIELD_NAME, false)),
+    config: object({ event: text, correlation: dataPath, saveTo }, ["event"]),
+  },
+  { kind: "exclusiveGateway", role: "gateway", check: none, config: object({}) },
+  { kind: "parallelGateway", role: "gateway", check: none, config: object({}) },
+  { kind: "boundaryError", role: "boundary", check: (c) => string(c, "errorCode", /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, false), config: object({ errorCode: text }) },
+  { kind: "boundaryTimer", role: "boundary", check: (c) => first(timer(c), boolean(c, "interrupting")), config: object({ ...timerConfig, interrupting: flag }) },
+  {
+    kind: "boundaryEvent",
+    role: "boundary",
+    check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), boolean(c, "interrupting")),
+    config: object({ event: text, correlation: dataPath, interrupting: flag }, ["event"]),
+  },
+  { kind: "end", role: "end", check: none, config: object({}) },
 ] satisfies NodeKindDefinition[]);
 
 const BY_KIND = new Map(NODE_KINDS.map((definition) => [definition.kind, definition]));

package/library/workflow/palette.ts

@@ -0,0 +1,110 @@
+import { EXPRESSION_FUNCTIONS, type ExprFunction } from "./expressions";
+import type { LocalizedText } from "./localized";
+import { NODE_KINDS, nodeKindOf, type JsonSchema, type NodeRole } from "./nodeKinds";
+import { DATA_PATHS } from "./paths";
+import type { NodeKind } from "./ProcessDocument";
+
+/** What the palette shows of a Tool: structurally a Tool contract. */
+export interface PaletteTool {
+  readonly name: string;
+  readonly description: string;
+  readonly input?: { readonly kind?: string; readonly schema?: unknown };
+  readonly output?: { readonly kind?: string; readonly schema?: unknown };
+  readonly sideEffect: string;
+  readonly dryRun: string;
+}
+
+export interface PaletteNodeKind {
+  readonly kind: NodeKind;
+  readonly role: NodeRole;
+  /** A container: other nodes name it as their `parent`. */
+  readonly container?: boolean;
+  readonly config: JsonSchema;
+}
+
+/** Everything a designer builds its forms from (WORKFLOW-002 §4.2). */
+export interface ProcessPalette {
+  readonly nodeKinds: readonly PaletteNodeKind[];
+  readonly functions: readonly ExprFunction[];
+  readonly paths: typeof DATA_PATHS;
+  readonly tools: readonly PaletteTool[];
+}
+
+/** The palette with the application's Tools: a new Tool appears in a designer without a release of the framework. */
+export function processPalette(tools: readonly PaletteTool[]): ProcessPalette {
+  return {
+    nodeKinds: NODE_KINDS.map(({ kind, role, container, config }) => ({ kind, role, ...(container === undefined ? {} : { container }), config })),
+    functions: EXPRESSION_FUNCTIONS,
+    paths: DATA_PATHS,
+    tools,
+  };
+}
+
+/** One field of the form of a step. */
+export interface StepFormField {
+  readonly name: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly title?: LocalizedText;
+  readonly description?: string;
+  readonly values?: readonly unknown[];
+  /** What the field references (`x-ref`), its keys reference (`x-ref-keys`) and the input that gives the area (`x-ref-scope`). */
+  readonly ref?: string;
+  readonly refKeys?: string;
+  readonly refScope?: string;
+  /** Personal data (`x-personal`). */
+  readonly personal?: boolean;
+  /** The fields of an object. */
+  readonly fields?: readonly StepFormField[];
+  /** A list's items. */
+  readonly items?: StepFormField;
+}
+
+export interface StepForm {
+  readonly fields: readonly StepFormField[];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function fieldOf(name: string, schema: unknown, required: boolean): StepFormField {
+  const source = isObject(schema) ? schema : {};
+  const values = Array.isArray(source.enum) ? source.enum : undefined;
+  const type = typeof source.type === "string" ? source.type : Array.isArray(source.type) ? String(source.type.find((item) => item !== "null") ?? "any") : values !== undefined ? "enum" : "any";
+  const fields = isObject(source.properties) ? fieldsOf(source) : undefined;
+  return {
+    name,
+    type,
+    required,
+    ...(source.title === undefined ? {} : { title: source.title as LocalizedText }),
+    ...(typeof source.description === "string" ? { description: source.description } : {}),
+    ...(values === undefined ? {} : { values }),
+    ...(typeof source["x-ref"] === "string" ? { ref: source["x-ref"] } : {}),
+    ...(typeof source["x-ref-keys"] === "string" ? { refKeys: source["x-ref-keys"] } : {}),
+    ...(typeof source["x-ref-scope"] === "string" ? { refScope: source["x-ref-scope"] } : {}),
+    ...(source["x-personal"] === true ? { personal: true } : {}),
+    ...(fields === undefined ? {} : { fields }),
+    ...(isObject(source.items) ? { items: fieldOf("item", source.items, false) } : {}),
+  };
+}
+
+function fieldsOf(schema: Record<string, unknown>): StepFormField[] {
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  return Object.entries(isObject(schema.properties) ? schema.properties : {}).map(([name, item]) => fieldOf(name, item, required.has(name)));
+}
+
+/**
+ * The form of a step's settings, by the palette (WORKFLOW-002 §3.8): the
+ * `config` of a node kind, or the input of a Tool: fields, types, references
+ * and localizable titles. An unknown kind has no fields.
+ */
+export function formOf(source: NodeKind | Pick<PaletteTool, "input">): StepForm {
+  if (typeof source === "string") {
+    const definition = nodeKindOf(source);
+    return { fields: definition === undefined ? [] : fieldsOf(definition.config as Record<string, unknown>) };
+  }
+  const schema = source.input?.schema;
+  return { fields: isObject(schema) ? fieldsOf(schema) : [] };
+}
+

package/library/workflow/paths.ts

@@ -1,12 +1,42 @@
-/** Instance data that conditions and step inputs read. */
+import { evaluateExpression, isExpressionNode } from "./expressions";
+
+/**
+ * What expressions and step inputs read. `input`, `vars` and `nodes` are the
+ * instance's own data; the rest describes the run. The engine fills them all.
+ */
 export interface InstanceData {
   readonly input: Readonly<Record<string, unknown>>;
   readonly vars: Readonly<Record<string, unknown>>;
   readonly nodes: Readonly<Record<string, unknown>>;
+  /** The data of the event that started or continued the process. */
+  readonly event?: unknown;
+  /** How it was started: `{ via, at, actor, eventKey?, cause? }`. */
+  readonly trigger?: unknown;
+  /** `{ id, processKey, version, partition, test }`. */
+  readonly run?: unknown;
+  /** The engine's time as an ISO string. */
+  readonly now?: string;
+  /** Inside a loop body: the element of this iteration. */
+  readonly item?: unknown;
+  /** Inside a loop body: the number of this iteration, from 0. */
+  readonly index?: number;
 }
 
-/** `$input.amount`, `$vars.payment.id`, `$nodes.Pay.paymentId`. */
-export const DATA_PATH = /^\$(input|vars|nodes)((\.[A-Za-z_][A-Za-z0-9_]*)+)$/;
+/** `$input.amount`, `$vars.payment.id`, `$nodes.Pay.paymentId`, `$event.record.id`, `$run.partition`, `$now`, `$item.id`, `$index`. */
+export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now|item|index)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
+
+/** The roots of `$` paths, for a designer. */
+export const DATA_PATHS: readonly { readonly path: string; readonly description: string }[] = Object.freeze([
+  { path: "$input.<field>", description: "A field of the process input: a variable with direction in" },
+  { path: "$vars.<name>", description: "A variable of the process" },
+  { path: "$nodes.<node>.<field>", description: "The result of a passed step" },
+  { path: "$event", description: "The data of the event that started or continued the process" },
+  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause? }" },
+  { path: "$run", description: "This run: { id, processKey, version, partition, test }" },
+  { path: "$now", description: "The engine's time" },
+  { path: "$item", description: "Inside a loop body: the element of this iteration" },
+  { path: "$index", description: "Inside a loop body: the number of this iteration, from 0" },
+]);
 
 /** `true` if the value is a path to instance data. */
 export function isPath(value: unknown): value is string {
@@ -18,7 +48,7 @@ export function readPath(data: InstanceData, path: string): unknown {
   const match = DATA_PATH.exec(path);
   if (!match) return undefined;
   let current: unknown = data[match[1] as keyof InstanceData];
-  for (const key of match[2]!.slice(1).split(".")) {
+  for (const key of match[2]!.split(".").slice(1)) {
     if (typeof current !== "object" || current === null || !Object.prototype.hasOwnProperty.call(current, key)) return undefined;
     current = (current as Record<string, unknown>)[key];
   }
@@ -26,11 +56,12 @@ export function readPath(data: InstanceData, path: string): unknown {
 }
 
 /**
- * A step input: a path string becomes the instance value, objects and lists are
- * resolved deeply, anything else is a literal. A missing value becomes `null`.
+ * A step input: a path string and an expression become their value, objects and
+ * lists are resolved deeply, anything else is a literal. A missing value becomes `null`.
  */
 export function resolveInput(value: unknown, data: InstanceData): unknown {
   if (isPath(value)) return readPath(data, value) ?? null;
+  if (isExpressionNode(value)) return evaluateExpression(value, data) ?? null;
   if (Array.isArray(value)) return value.map((item) => resolveInput(item, data));
   if (typeof value === "object" && value !== null) {
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolveInput(item, data)]));