bazis 0.131.0 → 0.132.0

package/library/workflow/formFields.ts

@@ -1,14 +1,31 @@
-/** Field types of a process input and of a task form. */
-export type FormFieldType = "string" | "text" | "number" | "integer" | "boolean" | "date" | "datetime" | "enum";
+import { checkLocalizedText, type LocalizedText } from "./localized";
 
+/** The types of variables and of task form fields. */
+export type FieldType = "string" | "text" | "number" | "integer" | "boolean" | "date" | "datetime" | "enum" | "object" | "list" | "ref";
+
+/** A field of a task form; a variable of a process is the same with a direction. */
 export interface FormField {
   /** The key in the value: `amount`, `reason`. */
-  readonly code: string;
-  readonly type: FormFieldType;
-  readonly title?: string;
+  readonly name: string;
+  readonly type: FieldType;
+  readonly title?: LocalizedText;
+  readonly default?: unknown;
   readonly required?: boolean;
   /** Allowed values of an `enum` field. */
   readonly values?: readonly (string | number)[];
+  /** For `ref`: the kind of reference, for example `orm.entity:Order`. */
+  readonly ref?: string;
+  /** Personal data: masked in the history under `log.maskPersonal`. */
+  readonly personal?: boolean;
+  /** The application's rules by namespace; `WorkflowInputValidator` reads them. */
+  readonly extensions?: Readonly<Record<string, unknown>>;
+}
+
+/** `in`: the input of a start. `local`: inside the process. `out`: what the process gives back. */
+export type VariableDirection = "in" | "local" | "out";
+
+export interface VariableSpec extends FormField {
+  readonly direction: VariableDirection;
 }
 
 /** The fields of a process input or a task form. */
@@ -24,8 +41,12 @@ export interface FormIssue {
   readonly message: string;
 }
 
-const TYPES = new Set<FormFieldType>(["string", "text", "number", "integer", "boolean", "date", "datetime", "enum"]);
-const CODE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const TYPES = new Set<FieldType>(["string", "text", "number", "integer", "boolean", "date", "datetime", "enum", "object", "list", "ref"]);
+const DIRECTIONS = new Set<VariableDirection>(["in", "local", "out"]);
+/** A variable or field name. */
+export const FIELD_NAME = /^[a-z][A-Za-z0-9_]{0,39}$/;
+const REF_KIND = /^[a-z][A-Za-z0-9_.:-]{0,127}$/;
+const NAMESPACE = /^[a-z][a-z0-9_-]{0,63}$/;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 const MAX_FIELDS = 200;
 
@@ -33,6 +54,46 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/** What is wrong with `extensions`, or `null`: an object of namespace → anything. */
+export function checkExtensions(value: unknown, at: string): string | null {
+  if (value === undefined) return null;
+  if (!isObject(value)) return `${at} must be an object of namespace → data`;
+  const bad = Object.keys(value).find((key) => !NAMESPACE.test(key));
+  return bad === undefined ? null : `${at} has an invalid namespace ${JSON.stringify(bad)}`;
+}
+
+/** What is wrong with one field, or `null`. */
+function checkField(field: unknown, where: string): string | null {
+  if (!isObject(field)) return `${where} must be an object`;
+  if (typeof field.name !== "string" || !FIELD_NAME.test(field.name)) return `${where}.name must match ${FIELD_NAME.source}`;
+  if (typeof field.type !== "string" || !TYPES.has(field.type as FieldType)) return `${where}.type must be one of ${[...TYPES].join(", ")}`;
+  if (field.title !== undefined) {
+    const problem = checkLocalizedText(field.title, 200);
+    if (problem) return `${where}.title ${problem}`;
+  }
+  if (field.required !== undefined && typeof field.required !== "boolean") return `${where}.required must be a boolean`;
+  if (field.personal !== undefined && typeof field.personal !== "boolean") return `${where}.personal must be a boolean`;
+  if (field.type === "enum") {
+    if (!Array.isArray(field.values) || field.values.length === 0 || !field.values.every((item) => typeof item === "string" || typeof item === "number")) {
+      return `${where}.values must be a non-empty list of strings or numbers`;
+    }
+  } else if (field.values !== undefined) {
+    return `${where}.values is only for enum fields`;
+  }
+  if (field.type === "ref") {
+    if (typeof field.ref !== "string" || !REF_KIND.test(field.ref)) return `${where}.ref must name a kind of reference`;
+  } else if (field.ref !== undefined) {
+    return `${where}.ref is only for ref fields`;
+  }
+  const extensions = checkExtensions(field.extensions, `${where}.extensions`);
+  if (extensions) return extensions;
+  if (field.default !== undefined && field.default !== null) {
+    const problem = checkType(field as unknown as FormField, field.default);
+    if (problem) return `${where}.default: ${problem.message}`;
+  }
+  return null;
+}
+
 /** Checks the shape of a form spec; returns a problem or `null`. `at` names it in the text. */
 export function checkFormSpec(value: unknown, at: string): string | null {
   if (!isObject(value) || !Array.isArray(value.fields)) return `${at} must be an object with a fields list`;
@@ -40,59 +101,77 @@ export function checkFormSpec(value: unknown, at: string): string | null {
   const seen = new Set<string>();
   for (const [index, field] of value.fields.entries()) {
     const where = `${at}.fields[${index}]`;
-    if (!isObject(field)) return `${where} must be an object`;
-    if (typeof field.code !== "string" || !CODE.test(field.code) || field.code === "__proto__") return `${where}.code is invalid`;
-    if (seen.has(field.code)) return `${where}.code ${field.code} is repeated`;
-    seen.add(field.code);
-    if (typeof field.type !== "string" || !TYPES.has(field.type as FormFieldType)) return `${where}.type must be one of ${[...TYPES].join(", ")}`;
-    if (field.title !== undefined && (typeof field.title !== "string" || field.title.length > 200)) return `${where}.title must be up to 200 characters`;
-    if (field.required !== undefined && typeof field.required !== "boolean") return `${where}.required must be a boolean`;
-    if (field.type === "enum") {
-      if (!Array.isArray(field.values) || field.values.length === 0 || !field.values.every((item) => typeof item === "string" || typeof item === "number")) {
-        return `${where}.values must be a non-empty list of strings or numbers`;
-      }
-    } else if (field.values !== undefined) {
-      return `${where}.values is only for enum fields`;
-    }
+    const problem = checkField(field, where);
+    if (problem) return problem;
+    if (isObject(field) && Object.hasOwn(field, "direction")) return `${where}: a form field has no direction`;
+    const name = (field as FormField).name;
+    if (seen.has(name)) return `${where}.name ${name} is repeated`;
+    seen.add(name);
   }
   return null;
 }
 
-/** The field codes of a form spec. */
-export function formFieldCodes(spec: FormSpec): string[] {
-  return spec.fields.map((field) => field.code);
+/** Every problem of the variables of a document, with the variable it is about. */
+export function variableProblems(value: unknown): readonly { readonly variable?: string; readonly message: string }[] {
+  if (!Array.isArray(value)) return [{ message: "variables must be a list" }];
+  if (value.length > MAX_FIELDS) return [{ message: `there are more than ${MAX_FIELDS} variables` }];
+  const out: { variable?: string; message: string }[] = [];
+  const seen = new Set<string>();
+  for (const [index, variable] of value.entries()) {
+    const where = `variables[${index}]`;
+    const name = isObject(variable) && typeof variable.name === "string" ? variable.name : undefined;
+    const at = name === undefined ? {} : { variable: name };
+    const problem = checkField(variable, where);
+    if (problem) {
+      out.push({ ...at, message: problem });
+      continue;
+    }
+    const spec = variable as Record<string, unknown>;
+    if (typeof spec.direction !== "string" || !DIRECTIONS.has(spec.direction as VariableDirection)) out.push({ ...at, message: `${where}.direction must be in, local or out` });
+    else if (spec.required !== undefined && spec.direction !== "in") out.push({ ...at, message: `${where}.required is only for in variables` });
+    if (seen.has(name!)) out.push({ ...at, message: `${where}.name ${name} is repeated` });
+    seen.add(name!);
+  }
+  return out;
+}
+
+/** The field names of a form spec. */
+export function formFieldNames(spec: FormSpec): string[] {
+  return spec.fields.map((field) => field.name);
 }
 
 /**
  * Checks a value against a form spec: required fields, types, enum values and
- * unknown fields. Returns the value with only the declared fields and every issue.
- * Without a spec the form takes no data: any field is unknown.
+ * unknown fields; a missing field takes its `default`. Returns the value with
+ * only the declared fields and every issue. Without a spec the form takes no
+ * data: any field is unknown.
  */
 export function validateForm(spec: FormSpec | undefined, value: unknown): { readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] } {
   const issues: FormIssue[] = [];
   const source = value === undefined || value === null ? {} : value;
   if (!isObject(source)) return { value: {}, issues: [{ field: "", code: "type", message: "value must be an object" }] };
   const fields = spec?.fields ?? [];
-  const declared = new Set(fields.map((field) => field.code));
+  const declared = new Set(fields.map((field) => field.name));
   for (const key of Object.keys(source)) {
     if (!declared.has(key)) issues.push({ field: key, code: "unknown", message: `field ${key} is not declared` });
   }
   const out: Record<string, unknown> = {};
   for (const field of fields) {
-    const item = Object.hasOwn(source, field.code) ? source[field.code] : undefined;
+    const given = Object.hasOwn(source, field.name) ? source[field.name] : undefined;
+    const item = given === undefined || given === null || given === "" ? field.default : given;
     if (item === undefined || item === null || item === "") {
-      if (field.required === true) issues.push({ field: field.code, code: "required", message: `field ${field.code} is required` });
+      if (field.required === true) issues.push({ field: field.name, code: "required", message: `field ${field.name} is required` });
       continue;
     }
     const problem = checkType(field, item);
-    if (problem) issues.push({ field: field.code, ...problem });
-    else out[field.code] = item;
+    if (problem) issues.push({ field: field.name, ...problem });
+    else out[field.name] = item;
   }
   return { value: out, issues };
 }
 
 function checkType(field: FormField, value: unknown): { code: "type" | "enum"; message: string } | null {
-  const wrong = (expected: string) => ({ code: "type" as const, message: `field ${field.code} must be ${expected}` });
+  const wrong = (expected: string) => ({ code: "type" as const, message: `field ${field.name} must be ${expected}` });
   switch (field.type) {
     case "string":
     case "text":
@@ -108,6 +187,12 @@ function checkType(field: FormField, value: unknown): { code: "type" | "enum"; m
     case "datetime":
       return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? null : wrong("an ISO 8601 date and time");
     case "enum":
-      return (field.values ?? []).includes(value as string | number) ? null : { code: "enum", message: `field ${field.code} must be one of ${(field.values ?? []).join(", ")}` };
+      return (field.values ?? []).includes(value as string | number) ? null : { code: "enum", message: `field ${field.name} must be one of ${(field.values ?? []).join(", ")}` };
+    case "object":
+      return isObject(value) ? null : wrong("an object");
+    case "list":
+      return Array.isArray(value) ? null : wrong("a list");
+    case "ref":
+      return (typeof value === "string" && value !== "") || typeof value === "number" ? null : wrong("a reference: a string or a number");
   }
 }

package/library/workflow/index.ts

@@ -1,26 +1,65 @@
 /**
- * The process document format `bazis.workflow/v1` (WORKFLOW-001 §2): types,
- * node kinds, validation, data paths and conditions. Pure functions without DI
- * or a database: usable by a designer, a CLI or a browser.
+ * The process document format `bazis.workflow/v2` (WORKFLOW-002 §3): types,
+ * node kinds, validation, data paths and expressions, the upgrade from version 1
+ * and the core of a designer. Pure functions without DI or a database: usable by
+ * a designer, a CLI or a browser.
  */
 export {
   PROCESS_SCHEMA_VERSION,
   emptyProcess,
+  initialVarsOf,
+  inputSpecOf,
+  outputOf,
   type Bounds,
-  type Condition,
-  type ConditionOp,
   type NodeKind,
   type Point,
   type ProcessDiagram,
   type ProcessDocument,
   type ProcessFlow,
+  type ProcessLogSettings,
   type ProcessNode,
+  type ProcessSettings,
 } from "./ProcessDocument";
-export { NODE_KINDS, nodeKindOf, ISO_DURATION, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
+export { NODE_KINDS, nodeKindOf, ISO_DURATION, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
-export { DATA_PATH, isPath, readPath, resolveInput, type InstanceData } from "./paths";
-export { evaluateCondition } from "./conditions";
+export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, type InstanceData } from "./paths";
+export {
+  EXPRESSION_FUNCTIONS,
+  EXPRESSION_LIMITS,
+  checkExpression,
+  checkPath,
+  evaluateExpression,
+  expressionFunction,
+  isExpressionNode,
+  isTruthy,
+  type Expr,
+  type ExprCall,
+  type ExpressionScope,
+  type ExprFunction,
+  type ExprFunctionName,
+  type ExprPath,
+  type ExprType,
+} from "./expressions";
+export { ExpressionSyntaxError, parseExpression, printExpression } from "./expressionSyntax";
 export { durationMs } from "./duration";
 export { parseCron, type CronSchedule } from "./cron";
 export { processToMermaid } from "./mermaid";
-export { checkFormSpec, formFieldCodes, validateForm, type FormField, type FormFieldType, type FormIssue, type FormSpec } from "./formFields";
+export { PERSONAL_MASK, maskByMapping, maskBySchema, masksPersonal, personalPaths, personalVariables, readsPersonal } from "./masking";
+export { allTexts, checkLocalizedText, textOf, type LocalizedText } from "./localized";
+export {
+  FIELD_NAME,
+  checkExtensions,
+  checkFormSpec,
+  formFieldNames,
+  validateForm,
+  variableProblems,
+  type FieldType,
+  type FormField,
+  type FormIssue,
+  type FormSpec,
+  type VariableDirection,
+  type VariableSpec,
+} from "./formFields";
+export { PROCESS_SCHEMA_VERSION_V1, upgradeCondition, upgradeDocument, type ConditionV1, type FormFieldV1, type ProcessDocumentV1 } from "./upgradeDocument";
+export { fromStructure, isStructured, toStructure, type ProcessStructure, type StructureBoundary, type StructureBranch, type StructureStart, type StructureStep } from "./structure";
+export { formOf, processPalette, type PaletteNodeKind, type PaletteTool, type ProcessPalette, type StepForm, type StepFormField } from "./palette";

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,58 @@
+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`. */
+export function personalPaths(document: Pick<ProcessDocument, "variables">): ReadonlySet<string> {
+  return new Set((document.variables ?? []).filter((variable) => variable.personal === true).map((variable) => `${variable.direction === "in" ? "$input" : "$vars"}.${variable.name}`));
+}
+
+/** 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,7 @@ const SHAPES: Record<NodeKind, readonly [open: string, close: string]> = {
   end: ["((", "))"],
   userTask: ["[", "]"],
   serviceTask: ["[[", "]]"],
+  assign: ["[/", "/]"],
   timerCatch: ["{{", "}}"],
   eventWait: ["{{", "}}"],
   exclusiveGateway: ["{", "}"],
@@ -42,14 +46,14 @@ export function processToMermaid(document: ProcessDocument, direction: "LR" | "T
   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}`);
+    lines.push(`  ${idOf(nodeId)}${open}"${label(textOf(node.title, "en") || nodeId)}${detail === undefined ? "" : `<br/><small>${label(detail)}</small>`}"${close}`);
   }
   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`;
@@ -70,15 +74,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,29 @@
 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;
   /** 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 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 +79,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 +89,89 @@ 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;
+}
+
+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: "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]));