bazis 0.131.0 → 0.132.0

package/library/workflow/palette.ts

@@ -0,0 +1,108 @@
+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;
+  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, config }) => ({ kind, role, 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,36 @@
-/** 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;
 }
 
-/** `$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`. */
+export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now)((\.[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" },
+]);
 
 /** `true` if the value is a path to instance data. */
 export function isPath(value: unknown): value is string {
@@ -18,7 +42,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 +50,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)]));

package/library/workflow/structure.ts

@@ -0,0 +1,282 @@
+import type { ProcessDiagram, ProcessDocument, ProcessFlow, ProcessNode, ProcessSettings } from "./ProcessDocument";
+import type { Expr } from "./expressions";
+import type { VariableSpec } from "./formFields";
+import type { LocalizedText } from "./localized";
+import { nodeKindOf } from "./nodeKinds";
+
+/** One branch of a fork: the flow it leaves by and its steps. */
+export interface StructureBranch {
+  readonly flow: string;
+  readonly title?: LocalizedText;
+  readonly condition?: Expr;
+  readonly isDefault?: boolean;
+  /** The flow from its last step into the merge or the end; `flow` itself for an empty branch. */
+  readonly exit: string;
+  readonly exitTitle?: LocalizedText;
+  readonly steps: readonly StructureStep[];
+}
+
+/** A boundary event of a step and what it leads to. */
+export interface StructureBoundary {
+  readonly id: string;
+  readonly node: ProcessNode;
+  readonly flow: string;
+  readonly title?: LocalizedText;
+  readonly steps: readonly StructureStep[];
+  /** The end its branch leads to; without it the branch comes back to the step after the host. */
+  readonly end?: { readonly id: string; readonly node: ProcessNode; readonly flow: string; readonly title?: LocalizedText };
+  /** The flow that comes back when the branch has steps and no end of its own. */
+  readonly exit?: string;
+  readonly exitTitle?: LocalizedText;
+}
+
+/** A step of the list: a single node, an exclusive fork or a parallel block. */
+export type StructureStep =
+  | {
+    readonly type: "step";
+    readonly id: string;
+    readonly node: ProcessNode;
+    readonly boundaries?: readonly StructureBoundary[];
+    /** The flow to the next step. */
+    readonly next: string;
+    readonly nextTitle?: LocalizedText;
+  }
+  | {
+    readonly type: "choice" | "parallel";
+    readonly id: string;
+    readonly node: ProcessNode;
+    readonly branches: readonly StructureBranch[];
+    /** Where the branches meet; without it they all lead to the end, and the fork is the last step of its list. */
+    readonly merge?: { readonly id: string; readonly node: ProcessNode; readonly next: string; readonly nextTitle?: LocalizedText };
+  };
+
+/** A start of the list and the flow from it to the first step. */
+export interface StructureStart {
+  readonly id: string;
+  readonly node: ProcessNode;
+  readonly flow: string;
+  readonly title?: LocalizedText;
+}
+
+/** A process as a designer draws it: starts, a list of steps, an end. */
+export interface ProcessStructure {
+  readonly variables?: readonly VariableSpec[];
+  readonly settings?: ProcessSettings;
+  readonly diagram?: ProcessDiagram;
+  readonly extensions?: Readonly<Record<string, unknown>>;
+  readonly schemaVersion: ProcessDocument["schemaVersion"];
+  readonly starts: readonly StructureStart[];
+  readonly steps: readonly StructureStep[];
+  readonly end: { readonly id: string; readonly node: ProcessNode };
+}
+
+class NotStructured extends Error {}
+
+const titleOf = (flow: ProcessFlow) => (flow.title === undefined ? {} : { title: flow.title });
+
+/** Reads a graph as a tree; a shape outside the subset throws {@link NotStructured}. */
+class Reader {
+  private readonly outgoing = new Map<string, (readonly [string, ProcessFlow])[]>();
+  private readonly incoming = new Map<string, (readonly [string, ProcessFlow])[]>();
+  private readonly boundaries = new Map<string, (readonly [string, ProcessNode])[]>();
+  private readonly visited = new Set<string>();
+
+  constructor(private readonly document: ProcessDocument) {
+    for (const [id, flow] of Object.entries(document.flows)) {
+      this.outgoing.set(flow.source, [...this.outgoing.get(flow.source) ?? [], [id, flow]]);
+      this.incoming.set(flow.target, [...this.incoming.get(flow.target) ?? [], [id, flow]]);
+    }
+    for (const [id, node] of Object.entries(document.nodes)) {
+      if (node.attachedTo !== undefined) this.boundaries.set(node.attachedTo, [...this.boundaries.get(node.attachedTo) ?? [], [id, node]]);
+    }
+  }
+
+  private node(id: string): ProcessNode {
+    const node = this.document.nodes[id];
+    if (!node) throw new NotStructured();
+    return node;
+  }
+
+  private single(id: string): readonly [string, ProcessFlow] {
+    const flows = this.outgoing.get(id) ?? [];
+    if (flows.length !== 1) throw new NotStructured();
+    return flows[0]!;
+  }
+
+  private visit(id: string): void {
+    if (this.visited.has(id)) throw new NotStructured();
+    this.visited.add(id);
+  }
+
+  read(): ProcessStructure {
+    const { nodes: _nodes, flows: _flows, ...rest } = this.document;
+    const entries = Object.entries(this.document.nodes);
+    const starts = entries.filter(([, node]) => nodeKindOf(node.kind)?.role === "start");
+    if (starts.length === 0) throw new NotStructured();
+    const shaped = starts.map(([id, node]) => {
+      const [flow, { target, ...data }] = this.single(id);
+      return { start: { id, node, flow, ...titleOf({ ...data, target }) }, target };
+    });
+    const first = shaped[0]!.target;
+    if (shaped.some(({ target }) => target !== first)) throw new NotStructured();
+    for (const { start } of shaped) this.visit(start.id);
+    const { steps, stop } = this.sequence(first);
+    const end = this.node(stop);
+    if (nodeKindOf(end.kind)?.role !== "end") throw new NotStructured();
+    this.visited.add(stop);
+    if (this.visited.size !== entries.length) throw new NotStructured();
+    return { ...rest, starts: shaped.map(({ start }) => start), steps, end: { id: stop, node: end } };
+  }
+
+  /** Steps from `from` up to a merge or an end, which is not taken. */
+  private sequence(from: string): { readonly steps: StructureStep[]; readonly stop: string; readonly exit?: { readonly flow: string; readonly title?: LocalizedText } } {
+    const steps: StructureStep[] = [];
+    let current = from;
+    let exit: { flow: string; title?: LocalizedText } | undefined;
+    for (;;) {
+      const node = this.node(current);
+      const role = nodeKindOf(node.kind)?.role;
+      if (role === "end") return { steps, stop: current, ...(exit === undefined ? {} : { exit }) };
+      if (role === "activity") {
+        this.visit(current);
+        const [flowId, flow] = this.single(current);
+        const boundaries = (this.boundaries.get(current) ?? []).map(([id, boundary]) => this.boundary(id, boundary, flow.target));
+        steps.push({ type: "step", id: current, node, ...(boundaries.length === 0 ? {} : { boundaries }), next: flowId, ...(flow.title === undefined ? {} : { nextTitle: flow.title }) });
+        exit = { flow: flowId, ...(flow.title === undefined ? {} : { title: flow.title }) };
+        current = flow.target;
+        continue;
+      }
+      if (role !== "gateway") throw new NotStructured();
+      const outs = this.outgoing.get(current) ?? [];
+      // A join: whoever walks here stops; the fork that owns it goes on from it.
+      if (outs.length === 1) return { steps, stop: current, ...(exit === undefined ? {} : { exit }) };
+      const { step, stop } = this.fork(current, node, outs);
+      steps.push(step);
+      if (step.merge === undefined) return { steps, stop };
+      exit = { flow: step.merge.next, ...(step.merge.nextTitle === undefined ? {} : { title: step.merge.nextTitle }) };
+      current = this.document.flows[step.merge.next]!.target;
+    }
+  }
+
+  private fork(id: string, node: ProcessNode, outs: readonly (readonly [string, ProcessFlow])[]): { readonly step: Extract<StructureStep, { type: "choice" | "parallel" }>; readonly stop: string } {
+    if ((this.incoming.get(id)?.length ?? 0) !== 1) throw new NotStructured();
+    this.visit(id);
+    let merge: string | undefined;
+    const branches = outs.map(([flowId, flow]): StructureBranch => {
+      const { steps, stop, exit } = this.sequence(flow.target);
+      if (merge !== undefined && merge !== stop) throw new NotStructured();
+      merge = stop;
+      return {
+        flow: flowId,
+        ...titleOf(flow),
+        ...(flow.condition === undefined ? {} : { condition: flow.condition }),
+        ...(flow.isDefault === undefined ? {} : { isDefault: flow.isDefault }),
+        exit: exit?.flow ?? flowId,
+        ...(exit?.title === undefined ? {} : { exitTitle: exit.title }),
+        steps,
+      };
+    });
+    const type = node.kind === "parallelGateway" ? "parallel" : "choice";
+    const mergeNode = this.node(merge!);
+    if (nodeKindOf(mergeNode.kind)?.role === "end") return { step: { type, id, node, branches }, stop: merge! };
+    if (mergeNode.kind !== node.kind) throw new NotStructured();
+    this.visit(merge!);
+    const [next, nextFlow] = this.single(merge!);
+    return { step: { type, id, node, branches, merge: { id: merge!, node: mergeNode, next, ...(nextFlow.title === undefined ? {} : { nextTitle: nextFlow.title }) } }, stop: merge! };
+  }
+
+  private boundary(id: string, node: ProcessNode, after: string): StructureBoundary {
+    this.visit(id);
+    const [flow, data] = this.single(id);
+    const base = { id, node, flow, ...titleOf(data) };
+    if (data.target === after) return { ...base, steps: [] };
+    const { steps, stop, exit } = this.sequence(data.target);
+    const stopNode = this.node(stop);
+    if (stop === after) {
+      if (exit === undefined) throw new NotStructured();
+      return { ...base, steps, exit: exit.flow, ...(exit.title === undefined ? {} : { exitTitle: exit.title }) };
+    }
+    // An end: its own, or the end of the process. A list without steps leads to it by the boundary's own flow.
+    if (nodeKindOf(stopNode.kind)?.role !== "end") throw new NotStructured();
+    this.visited.add(stop);
+    const last = exit ?? { flow, ...titleOf(data) };
+    return { ...base, steps, end: { id: stop, node: stopNode, flow: last.flow, ...(last.title === undefined ? {} : { title: last.title }) } };
+  }
+}
+
+/**
+ * A graph as a tree of steps, or `undefined` when it is outside the subset a
+ * list can draw (WORKFLOW-002 §3.6): sequences, an exclusive gateway with one
+ * merge, a parallel gateway with a join, boundary events on steps.
+ */
+export function toStructure(document: ProcessDocument): ProcessStructure | undefined {
+  try {
+    return new Reader(document).read();
+  } catch (error) {
+    if (error instanceof NotStructured) return undefined;
+    throw error;
+  }
+}
+
+/** Whether a designer can edit the process as a list. Otherwise it shows the graph read only. */
+export function isStructured(document: ProcessDocument): boolean {
+  return toStructure(document) !== undefined;
+}
+
+/** A tree of steps as a graph: `fromStructure(toStructure(d))` has the nodes and flows of `d`. */
+export function fromStructure(structure: ProcessStructure): ProcessDocument {
+  const { starts, steps, end, ...rest } = structure;
+  const nodes: Record<string, ProcessNode> = {};
+  const flows: Record<string, ProcessFlow> = {};
+  const flow = (id: string, source: string, target: string, data: Partial<ProcessFlow> = {}) => {
+    flows[id] = { source, target, ...data };
+  };
+  const titled = (title: LocalizedText | undefined) => (title === undefined ? {} : { title });
+
+  /** The first node of a list, or where it goes when it is empty. */
+  const entry = (list: readonly StructureStep[], after: string) => list[0]?.id ?? after;
+
+  /** Writes a list that leads to `after`; `leave` writes the flow out of its last step. */
+  const write = (list: readonly StructureStep[], after: string, leave?: { readonly flow: string; readonly title?: LocalizedText }) => {
+    list.forEach((step, index) => {
+      const target = index + 1 < list.length ? list[index + 1]!.id : after;
+      const last = index + 1 === list.length && leave !== undefined;
+      nodes[step.id] = step.node;
+      if (step.type === "step") {
+        flow(last ? leave.flow : step.next, step.id, target, titled(last ? leave.title : step.nextTitle));
+        for (const boundary of step.boundaries ?? []) writeBoundary(boundary, step, target);
+        return;
+      }
+      const meet = step.merge?.id ?? target;
+      for (const branch of step.branches) {
+        const { flow: id, title, condition, isDefault, steps: inner, exit, exitTitle } = branch;
+        flow(id, step.id, entry(inner, meet), { ...titled(title), ...(condition === undefined ? {} : { condition }), ...(isDefault === undefined ? {} : { isDefault }) });
+        write(inner, meet, inner.length === 0 ? undefined : { flow: exit, ...(exitTitle === undefined ? {} : { title: exitTitle }) });
+      }
+      if (step.merge === undefined) return;
+      nodes[step.merge.id] = step.merge.node;
+      flow(last ? leave.flow : step.merge.next, step.merge.id, target, titled(last ? leave.title : step.merge.nextTitle));
+    });
+  };
+
+  const writeBoundary = (boundary: StructureBoundary, _host: StructureStep, after: string) => {
+    nodes[boundary.id] = boundary.node;
+    const target = boundary.end?.id ?? after;
+    flow(boundary.flow, boundary.id, entry(boundary.steps, target), titled(boundary.title));
+    if (boundary.end !== undefined) nodes[boundary.end.id] = boundary.end.node;
+    const leave = boundary.end !== undefined
+      ? { flow: boundary.end.flow, ...(boundary.end.title === undefined ? {} : { title: boundary.end.title }) }
+      : boundary.exit === undefined ? undefined : { flow: boundary.exit, ...(boundary.exitTitle === undefined ? {} : { title: boundary.exitTitle }) };
+    write(boundary.steps, target, boundary.steps.length === 0 ? undefined : leave);
+  };
+
+  const first = entry(steps, end.id);
+  for (const start of starts) {
+    nodes[start.id] = start.node;
+    flow(start.flow, start.id, first, titled(start.title));
+  }
+  write(steps, end.id);
+  nodes[end.id] = end.node;
+  return { ...rest, nodes, flows };
+}
+

package/library/workflow/upgradeDocument.ts

@@ -0,0 +1,84 @@
+import type { Expr } from "./expressions";
+import type { VariableSpec } from "./formFields";
+import { isPath } from "./paths";
+import { PROCESS_SCHEMA_VERSION, type ProcessDocument, type ProcessFlow, type ProcessNode } from "./ProcessDocument";
+
+/** The version 1 of the format, for {@link upgradeDocument}. */
+export const PROCESS_SCHEMA_VERSION_V1 = "bazis.workflow/v1";
+
+/** A condition of version 1: a tree of `all` / `any` / `not` and comparisons. */
+export type ConditionV1 =
+  | { readonly all: readonly ConditionV1[] }
+  | { readonly any: readonly ConditionV1[] }
+  | { readonly not: ConditionV1 }
+  | { readonly path: string; readonly op: string; readonly value?: unknown };
+
+export interface FormFieldV1 {
+  readonly code: string;
+  readonly type: string;
+  readonly title?: string;
+  readonly required?: boolean;
+  readonly values?: readonly (string | number)[];
+}
+
+export interface ProcessDocumentV1 {
+  readonly schemaVersion: typeof PROCESS_SCHEMA_VERSION_V1;
+  readonly input?: { readonly fields: readonly FormFieldV1[] };
+  readonly nodes: Readonly<Record<string, { readonly kind: string; readonly title: string; readonly attachedTo?: string; readonly config?: Readonly<Record<string, unknown>> }>>;
+  readonly flows: Readonly<Record<string, { readonly source: string; readonly target: string; readonly title?: string; readonly condition?: ConditionV1; readonly isDefault?: boolean }>>;
+  readonly diagram?: ProcessDocument["diagram"];
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A document of version 1 as version 2: `input` becomes `in` variables, form
+ * fields take `name` instead of `code`, conditions become expressions, titles
+ * stay as they are. A pure function. A draft may hold errors, so what is not of
+ * the expected shape is left as it is for the validation to report; anything
+ * that is not version 1 comes back unchanged.
+ */
+export function upgradeDocument(document: ProcessDocumentV1): ProcessDocument;
+export function upgradeDocument(document: unknown): unknown;
+export function upgradeDocument(document: unknown): unknown {
+  if (!isObject(document) || document.schemaVersion !== PROCESS_SCHEMA_VERSION_V1) return document;
+  const { input, nodes, flows, ...rest } = document;
+  const fields = isObject(input) && Array.isArray(input.fields) ? input.fields : undefined;
+  return {
+    ...rest,
+    schemaVersion: PROCESS_SCHEMA_VERSION,
+    ...(fields === undefined ? {} : { variables: fields.map((field) => upgradeField(field, "in")) }),
+    nodes: isObject(nodes) ? Object.fromEntries(Object.entries(nodes).map(([id, node]) => [id, upgradeNode(node)])) : nodes,
+    flows: isObject(flows) ? Object.fromEntries(Object.entries(flows).map(([id, flow]) => [id, upgradeFlow(flow)])) : flows,
+  };
+}
+
+function upgradeField(field: unknown, direction?: VariableSpec["direction"]): unknown {
+  if (!isObject(field)) return field;
+  const { code, ...rest } = field;
+  return { name: code, ...rest, ...(direction === undefined ? {} : { direction }) };
+}
+
+function upgradeNode(node: unknown): ProcessNode | unknown {
+  if (!isObject(node) || !isObject(node.config) || !isObject(node.config.form) || !Array.isArray(node.config.form.fields)) return node;
+  return { ...node, config: { ...node.config, form: { ...node.config.form, fields: node.config.form.fields.map((field) => upgradeField(field)) } } };
+}
+
+function upgradeFlow(flow: unknown): ProcessFlow | unknown {
+  if (!isObject(flow) || flow.condition === undefined) return flow;
+  return { ...flow, condition: upgradeCondition(flow.condition) };
+}
+
+/** `all` → `and`, `any` → `or`, `not` → `not`, a comparison → a call with the path first. */
+export function upgradeCondition(condition: unknown): Expr {
+  if (!isObject(condition)) return condition as Expr;
+  if (Array.isArray(condition.all)) return { op: "and", args: condition.all.map(upgradeCondition) };
+  if (Array.isArray(condition.any)) return { op: "or", args: condition.any.map(upgradeCondition) };
+  if (condition.not !== undefined) return { op: "not", args: [upgradeCondition(condition.not)] };
+  if (typeof condition.path !== "string" || typeof condition.op !== "string") return condition as Expr;
+  const path = { path: condition.path };
+  if (condition.value === undefined) return { op: condition.op, args: [path] } as Expr;
+  return { op: condition.op, args: [path, isPath(condition.value) ? { path: condition.value } : condition.value as Expr] } as Expr;
+}