@cyoda/workflow-core 0.1.0 → 0.2.0

package/dist/index.js

@@ -30,6 +30,14 @@ var OPERATOR_TYPES = /* @__PURE__ */ new Set([
   "IS_CHANGED"
 ]);
 
+// src/types/transaction.ts
+var PatchConflictError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PatchConflictError";
+  }
+};
+
 // src/types/api.ts
 var WorkflowApiConflictError = class extends Error {
   constructor(entity, serverConcurrencyToken, message = "Workflow save conflict: server state has changed.") {
@@ -144,11 +152,17 @@ var FunctionCriterionSchema = z3.lazy(
 
 // src/schema/processor.ts
 import { z as z4 } from "zod";
-var ExecutionModeSchema = z4.enum(["SYNC", "ASYNC_SAME_TX", "ASYNC_NEW_TX"]);
+var ExecutionModeSchema = z4.enum([
+  "SYNC",
+  "ASYNC_SAME_TX",
+  "ASYNC_NEW_TX",
+  "COMMIT_BEFORE_DISPATCH"
+]);
 var ExternalizedProcessorSchema = z4.object({
   type: z4.literal("externalized"),
   name: NameSchema,
   executionMode: ExecutionModeSchema.optional(),
+  startNewTxOnDispatch: z4.boolean().optional(),
   config: FunctionConfigSchema.and(
     z4.object({
       asyncResult: z4.boolean().optional(),
@@ -176,7 +190,7 @@ var TransitionSchema = z5.object({
   name: NameSchema,
   next: NameSchema,
   manual: z5.boolean(),
-  disabled: z5.boolean(),
+  disabled: z5.boolean().default(false),
   criterion: CriterionSchema.optional(),
   processors: z5.array(ProcessorSchema).optional()
 });
@@ -389,6 +403,118 @@ function mintCriterionIds(c, host, path, ids) {
   }
 }
 
+// src/criteria/operators.ts
+var SUPPORTED_SIMPLE_OPERATORS = /* @__PURE__ */ new Set([
+  "EQUALS",
+  "NOT_EQUAL",
+  "GREATER_THAN",
+  "LESS_THAN",
+  "GREATER_OR_EQUAL",
+  "LESS_OR_EQUAL",
+  "CONTAINS",
+  "NOT_CONTAINS",
+  "STARTS_WITH",
+  "NOT_STARTS_WITH",
+  "ENDS_WITH",
+  "NOT_ENDS_WITH",
+  "LIKE",
+  "IS_NULL",
+  "NOT_NULL",
+  "BETWEEN",
+  "BETWEEN_INCLUSIVE",
+  "MATCHES_PATTERN",
+  "IEQUALS",
+  "INOT_EQUAL",
+  "ICONTAINS",
+  "INOT_CONTAINS",
+  "ISTARTS_WITH",
+  "INOT_STARTS_WITH",
+  "IENDS_WITH",
+  "INOT_ENDS_WITH"
+]);
+var UNSUPPORTED_OPERATORS = /* @__PURE__ */ new Set([
+  "IS_UNCHANGED",
+  "IS_CHANGED"
+]);
+var SUPPORTED_GROUP_OPERATORS = ["AND", "OR"];
+var MAX_CRITERION_DEPTH = 50;
+var CRITERION_DEPTH_WARNING_THRESHOLD = 5;
+var OPERATOR_GROUPS = [
+  {
+    id: "equality",
+    label: "Equality",
+    operators: ["EQUALS", "NOT_EQUAL", "IEQUALS", "INOT_EQUAL"]
+  },
+  {
+    id: "ordering",
+    label: "Ordering",
+    operators: ["GREATER_THAN", "LESS_THAN", "GREATER_OR_EQUAL", "LESS_OR_EQUAL"]
+  },
+  {
+    id: "range",
+    label: "Range",
+    operators: ["BETWEEN", "BETWEEN_INCLUSIVE"]
+  },
+  {
+    id: "substring",
+    label: "Substring",
+    operators: [
+      "CONTAINS",
+      "NOT_CONTAINS",
+      "ICONTAINS",
+      "INOT_CONTAINS",
+      "STARTS_WITH",
+      "NOT_STARTS_WITH",
+      "ISTARTS_WITH",
+      "INOT_STARTS_WITH",
+      "ENDS_WITH",
+      "NOT_ENDS_WITH",
+      "IENDS_WITH",
+      "INOT_ENDS_WITH"
+    ]
+  },
+  {
+    id: "pattern",
+    label: "Pattern",
+    operators: ["LIKE", "MATCHES_PATTERN"]
+  },
+  {
+    id: "null",
+    label: "Null",
+    operators: ["IS_NULL", "NOT_NULL"]
+  }
+];
+var OPERATOR_VALUE_SHAPE = {
+  EQUALS: "scalar",
+  NOT_EQUAL: "scalar",
+  GREATER_THAN: "scalar",
+  LESS_THAN: "scalar",
+  GREATER_OR_EQUAL: "scalar",
+  LESS_OR_EQUAL: "scalar",
+  CONTAINS: "scalar",
+  NOT_CONTAINS: "scalar",
+  STARTS_WITH: "scalar",
+  NOT_STARTS_WITH: "scalar",
+  ENDS_WITH: "scalar",
+  NOT_ENDS_WITH: "scalar",
+  LIKE: "scalar",
+  MATCHES_PATTERN: "scalar",
+  IEQUALS: "scalar",
+  INOT_EQUAL: "scalar",
+  ICONTAINS: "scalar",
+  INOT_CONTAINS: "scalar",
+  ISTARTS_WITH: "scalar",
+  INOT_STARTS_WITH: "scalar",
+  IENDS_WITH: "scalar",
+  INOT_ENDS_WITH: "scalar",
+  BETWEEN: "range",
+  BETWEEN_INCLUSIVE: "range",
+  IS_NULL: "none",
+  NOT_NULL: "none",
+  IS_UNCHANGED: "none",
+  IS_CHANGED: "none"
+};
+
 // src/normalize/input.ts
 function normalizeWorkflowInput(workflow) {
   const out = {
@@ -431,12 +557,21 @@ function normalizeWorkflowInput(workflow) {
   }
   return out;
 }
-function normalizeCriterion(criterion) {
+function normalizeCriterion(criterion, depth = 0) {
+  if (depth >= MAX_CRITERION_DEPTH) {
+    return criterion;
+  }
   switch (criterion.type) {
     case "simple":
+      if (criterion.operation === "IS_NULL" || criterion.operation === "NOT_NULL") {
+        return { ...criterion, value: null };
+      }
       return criterion;
     case "group":
-      return { ...criterion, conditions: criterion.conditions.map(normalizeCriterion) };
+      return {
+        ...criterion,
+        conditions: criterion.conditions.map((c) => normalizeCriterion(c, depth + 1))
+      };
     case "function": {
       const fn = criterion.function;
       const out = {
@@ -444,12 +579,15 @@ function normalizeCriterion(criterion) {
         function: {
           name: fn.name.trim(),
           ...fn.config !== void 0 ? { config: fn.config } : {},
-          ...fn.criterion !== void 0 ? { criterion: normalizeCriterion(fn.criterion) } : {}
+          ...fn.criterion !== void 0 ? { criterion: normalizeCriterion(fn.criterion, depth + 1) } : {}
         }
       };
       return out;
     }
     case "lifecycle":
+      if (criterion.operation === "IS_NULL" || criterion.operation === "NOT_NULL") {
+        return { ...criterion, value: null };
+      }
       return criterion;
     case "array":
       return criterion;
@@ -466,6 +604,79 @@ function normalizeProcessor(p) {
   };
 }
 
+// src/criteria/jsonPathSubset.ts
+var SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+var INDEX_RE = /^(?:\d+|\*)$/;
+function validateJsonPathSubset(path) {
+  if (path.length === 0) return { ok: false, reason: "empty" };
+  if (path[0] !== "$") return { ok: false, reason: "missing-root" };
+  if (path === "$") return { ok: true };
+  let i = 1;
+  while (i < path.length) {
+    const ch = path[i];
+    if (ch === ".") {
+      if (path[i + 1] === ".") return { ok: false, reason: "recursive-descent" };
+      i += 1;
+      const start = i;
+      while (i < path.length && path[i] !== "." && path[i] !== "[") i += 1;
+      const segment = path.slice(start, i);
+      if (!SEGMENT_RE.test(segment)) return { ok: false, reason: "malformed" };
+      continue;
+    }
+    if (ch === "[") {
+      if (path[i + 1] === "?") return { ok: false, reason: "filter-expression" };
+      if (path[i + 1] === "'" || path[i + 1] === '"') return { ok: false, reason: "malformed" };
+      const end = path.indexOf("]", i);
+      if (end === -1) return { ok: false, reason: "malformed" };
+      const inner = path.slice(i + 1, end);
+      if (!INDEX_RE.test(inner)) return { ok: false, reason: "malformed" };
+      i = end + 1;
+      continue;
+    }
+    return { ok: false, reason: "malformed" };
+  }
+  return { ok: true };
+}
+
+// src/identity/id-for.ts
+function idFor(meta, ref) {
+  switch (ref.kind) {
+    case "workflow":
+      return meta.ids.workflows[ref.workflow] ?? null;
+    case "state": {
+      for (const [uuid, ptr] of Object.entries(meta.ids.states)) {
+        if (ptr.workflow === ref.workflow && ptr.state === ref.state) return uuid;
+      }
+      return null;
+    }
+    case "transition": {
+      const matches = [];
+      for (const [uuid, ptr] of Object.entries(meta.ids.transitions)) {
+        if (ptr.workflow === ref.workflow && ptr.state === ref.state) {
+          matches.push(uuid);
+        }
+      }
+      return matches[ref.ordinal] ?? null;
+    }
+    case "processor": {
+      const matches = [];
+      for (const [uuid, ptr] of Object.entries(meta.ids.processors)) {
+        if (ptr.transitionUuid === ref.transitionUuid) matches.push(uuid);
+      }
+      return matches[ref.ordinal] ?? null;
+    }
+    case "criterion": {
+      const target = JSON.stringify(ref.path);
+      for (const [uuid, ptr] of Object.entries(meta.ids.criteria)) {
+        if (JSON.stringify(ptr.host) === JSON.stringify(ref.host) && JSON.stringify(ptr.path) === target) {
+          return uuid;
+        }
+      }
+      return null;
+    }
+  }
+}
+
 // src/validate/helpers.ts
 function isValidName(name) {
   return NAME_REGEX.test(name);
@@ -491,12 +702,15 @@ function* walkCriteria(session) {
     }
   }
 }
-function* walkInner(c, where) {
+function* walkInner(c, where, depth = 0) {
   yield { criterion: c, where };
+  if (depth >= MAX_CRITERION_DEPTH) {
+    return;
+  }
   if (c.type === "group") {
-    for (const child of c.conditions) yield* walkInner(child, where);
+    for (const child of c.conditions) yield* walkInner(child, where, depth + 1);
   } else if (c.type === "function" && c.function.criterion) {
-    yield* walkInner(c.function.criterion, where);
+    yield* walkInner(c.function.criterion, where, depth + 1);
   }
 }
 
@@ -509,6 +723,8 @@ function validateSemantics(session, doc) {
     issues.push(...validateWorkflow(wf, doc));
   }
   issues.push(...criterionRules(session));
+  issues.push(...criterionDepthRules(session));
+  issues.push(...automatedOrderingRules(session, doc));
   if (session.workflows.length === 1) {
     const only = session.workflows[0];
     if (only && only.criterion !== void 0) {
@@ -546,14 +762,14 @@ function validateWorkflow(wf, doc) {
       severity: "error",
       code: "missing-initial-state",
       message: `Workflow "${wf.name}" has no initialState.`,
-      ...idFor(doc, wf.name, "workflow")
+      ...idFor2(doc, wf.name, "workflow")
     });
   } else if (!(wf.initialState in wf.states)) {
     issues.push({
       severity: "error",
       code: "unknown-initial-state",
       message: `Workflow "${wf.name}" initialState "${wf.initialState}" is not a state.`,
-      ...idFor(doc, wf.name, "workflow")
+      ...idFor2(doc, wf.name, "workflow")
     });
   }
   if (!isValidName(wf.name)) {
@@ -606,6 +822,13 @@ function validateWorkflow(wf, doc) {
               message: `Scheduled processor "${p.name}" has empty target transition.`
             });
           }
+          if (p.type === "externalized" && p.startNewTxOnDispatch === true && p.executionMode !== "COMMIT_BEFORE_DISPATCH") {
+            issues.push({
+              severity: "warning",
+              code: "start-new-tx-without-commit-before-dispatch",
+              message: `Processor "${p.name}" sets startNewTxOnDispatch but executionMode is not COMMIT_BEFORE_DISPATCH.`
+            });
+          }
           if (p.type === "externalized" && p.config) {
             if (p.config.crossoverToAsyncMs !== void 0 && p.config.asyncResult !== true) {
               issues.push({
@@ -748,7 +971,16 @@ function criterionRules(session) {
           });
         }
         break;
-      case "array":
+      case "array": {
+        const arrPathCheck = validateJsonPathSubset(criterion.jsonPath);
+        if (!arrPathCheck.ok) {
+          issues.push({
+            severity: "error",
+            code: "invalid-jsonpath-subset",
+            message: `Array criterion jsonPath "${criterion.jsonPath}" is not in the supported subset (${arrPathCheck.reason}) (at ${describe(where)}).`,
+            detail: { jsonPath: criterion.jsonPath, reason: arrPathCheck.reason }
+          });
+        }
         for (const v of criterion.value) {
           if (typeof v !== "string") {
             issues.push({
@@ -760,6 +992,7 @@ function criterionRules(session) {
           }
         }
         break;
+      }
       case "lifecycle":
         if (!LIFECYCLE_FIELDS.has(criterion.field)) {
           issues.push({
@@ -768,22 +1001,144 @@ function criterionRules(session) {
             message: `Lifecycle criterion field "${criterion.field}" is invalid.`
           });
         }
+        if (UNSUPPORTED_OPERATORS.has(criterion.operation)) {
+          issues.push({
+            severity: "warning",
+            code: "unsupported-operator",
+            message: `Operator "${criterion.operation}" is not implemented by the engine (at ${describe(where)}).`,
+            detail: { operation: criterion.operation }
+          });
+        }
         break;
       case "group":
-        if (criterion.operator === "NOT" && criterion.conditions.length > 1) {
+        if (criterion.operator === "NOT") {
           issues.push({
             severity: "warning",
-            code: "not-with-multiple-conditions",
-            message: `NOT group has ${criterion.conditions.length} conditions; should have exactly one.`
+            code: "unsupported-group-operator",
+            message: `Group operator "NOT" is not implemented by the engine (at ${describe(where)}).`,
+            detail: { operator: "NOT" }
           });
+          if (criterion.conditions.length > 1) {
+            issues.push({
+              severity: "warning",
+              code: "not-with-multiple-conditions",
+              message: `NOT group has ${criterion.conditions.length} conditions; should have exactly one.`
+            });
+          }
         }
         break;
-      case "simple":
+      case "simple": {
+        const pathCheck = validateJsonPathSubset(criterion.jsonPath);
+        if (!pathCheck.ok) {
+          issues.push({
+            severity: "error",
+            code: "invalid-jsonpath-subset",
+            message: `Simple criterion jsonPath "${criterion.jsonPath}" is not in the supported subset (${pathCheck.reason}) (at ${describe(where)}).`,
+            detail: { jsonPath: criterion.jsonPath, reason: pathCheck.reason }
+          });
+        } else if (criterion.jsonPath.startsWith("$._meta")) {
+          issues.push({
+            severity: "warning",
+            code: "lifecycle-path-in-simple",
+            message: `Simple criterion path "${criterion.jsonPath}" looks like a lifecycle path; use a lifecycle criterion instead (at ${describe(where)}).`,
+            detail: { jsonPath: criterion.jsonPath }
+          });
+        }
+        if (UNSUPPORTED_OPERATORS.has(criterion.operation)) {
+          issues.push({
+            severity: "warning",
+            code: "unsupported-operator",
+            message: `Operator "${criterion.operation}" is not implemented by the engine (at ${describe(where)}).`,
+            detail: { operation: criterion.operation }
+          });
+        }
+        if (criterion.operation === "BETWEEN" || criterion.operation === "BETWEEN_INCLUSIVE") {
+          if (!Array.isArray(criterion.value) || criterion.value.length !== 2) {
+            issues.push({
+              severity: "error",
+              code: "simple-between-shape",
+              message: `Operator "${criterion.operation}" requires a two-element [low, high] array value (at ${describe(where)}).`,
+              detail: { operation: criterion.operation }
+            });
+          }
+        }
+        if (criterion.operation === "LIKE" && typeof criterion.value === "string" && /[%_]/.test(criterion.value)) {
+          issues.push({
+            severity: "warning",
+            code: "like-wildcard-warning",
+            message: `LIKE pattern contains "%" or "_" which are always wildcards (no escape mechanism) (at ${describe(where)}).`
+          });
+        }
+        if (criterion.operation === "MATCHES_PATTERN" && typeof criterion.value === "string" && criterion.value.length > 0 && !criterion.value.startsWith("^") && !criterion.value.endsWith("$")) {
+          issues.push({
+            severity: "warning",
+            code: "matches-pattern-unanchored",
+            message: `MATCHES_PATTERN regex is unanchored; include "^"/"$" for whole-string match (at ${describe(where)}).`
+          });
+        }
         break;
+      }
     }
   }
   return issues;
 }
+function criterionDepthRules(session) {
+  const issues = [];
+  for (const wf of session.workflows) {
+    if (wf.criterion) {
+      pushDepthIssue(issues, criterionMaxDepth(wf.criterion), {
+        kind: "workflow",
+        workflow: wf.name
+      });
+    }
+    for (const [stateCode, state] of Object.entries(wf.states)) {
+      for (let i = 0; i < state.transitions.length; i++) {
+        const t = state.transitions[i];
+        if (!t.criterion) continue;
+        pushDepthIssue(issues, criterionMaxDepth(t.criterion), {
+          kind: "transition",
+          workflow: wf.name,
+          state: stateCode,
+          transitionIndex: i,
+          transitionName: t.name
+        });
+      }
+    }
+  }
+  return issues;
+}
+function pushDepthIssue(issues, maxDepth, where) {
+  if (maxDepth >= MAX_CRITERION_DEPTH) {
+    issues.push({
+      severity: "error",
+      code: "criterion-depth-limit",
+      message: `Criterion tree depth ${maxDepth} exceeds engine limit ${MAX_CRITERION_DEPTH} (at ${describe(where)}).`,
+      detail: { maxDepth, threshold: MAX_CRITERION_DEPTH }
+    });
+  }
+  if (maxDepth >= CRITERION_DEPTH_WARNING_THRESHOLD) {
+    issues.push({
+      severity: "warning",
+      code: "criterion-depth-warning",
+      message: `Criterion tree depth ${maxDepth} is hard to read; consider flattening (at ${describe(where)}).`,
+      detail: { maxDepth, threshold: CRITERION_DEPTH_WARNING_THRESHOLD }
+    });
+  }
+}
+function criterionMaxDepth(root) {
+  const stack = [{ node: root, depth: 1 }];
+  let max = 0;
+  while (stack.length > 0) {
+    const { node, depth } = stack.pop();
+    if (depth > max) max = depth;
+    if (node.type === "group") {
+      for (const child of node.conditions) stack.push({ node: child, depth: depth + 1 });
+    } else if (node.type === "function" && node.function.criterion) {
+      stack.push({ node: node.function.criterion, depth: depth + 1 });
+    }
+  }
+  return max;
+}
 function reachableStates(wf) {
   const visited = /* @__PURE__ */ new Set();
   if (!(wf.initialState in wf.states)) return visited;
@@ -832,11 +1187,65 @@ function describe(w) {
   if (w.kind === "workflow") return `workflow "${w.workflow}"`;
   return `transition "${w.transitionName}" on "${w.workflow}:${w.state}"`;
 }
-function idFor(doc, workflowName, _kind) {
+function idFor2(doc, workflowName, _kind) {
   if (!doc) return {};
   const id = doc.meta.ids.workflows[workflowName];
   return id ? { targetId: id } : {};
 }
+function transitionTargetId(doc, workflow, state, declarationIndex) {
+  if (!doc) return {};
+  const id = idFor(doc.meta, {
+    kind: "transition",
+    workflow,
+    state,
+    transitionName: "",
+    ordinal: declarationIndex
+  });
+  return id ? { targetId: id } : {};
+}
+function automatedOrderingRules(session, doc) {
+  const issues = [];
+  for (const wf of session.workflows) {
+    for (const [stateCode, state] of Object.entries(wf.states)) {
+      const automated = [];
+      state.transitions.forEach((t, index) => {
+        if (t.manual !== true && t.disabled !== true) {
+          automated.push({ index, t });
+        }
+      });
+      const nullIdx = automated.findIndex(({ t }) => t.criterion === void 0);
+      if (nullIdx === -1 || nullIdx === automated.length - 1) continue;
+      const nullEntry = automated[nullIdx];
+      issues.push({
+        severity: "warning",
+        code: "null-criterion-not-last",
+        message: `Transition "${nullEntry.t.name}" on state "${stateCode}" is automated and has no criterion, so it always fires; later automated transitions on this state are unreachable.`,
+        ...transitionTargetId(doc, wf.name, stateCode, nullEntry.index),
+        detail: {
+          workflow: wf.name,
+          state: stateCode,
+          transitionName: nullEntry.t.name
+        }
+      });
+      for (let j = nullIdx + 1; j < automated.length; j++) {
+        const dead = automated[j];
+        issues.push({
+          severity: "warning",
+          code: "unreachable-automated-transition",
+          message: `Transition "${dead.t.name}" on state "${stateCode}" is unreachable: an earlier automated transition ("${nullEntry.t.name}") has no criterion and will always fire first.`,
+          ...transitionTargetId(doc, wf.name, stateCode, dead.index),
+          detail: {
+            workflow: wf.name,
+            state: stateCode,
+            transitionName: dead.t.name,
+            blockedBy: nullEntry.t.name
+          }
+        });
+      }
+    }
+  }
+  return issues;
+}
 
 // src/validate/schema.ts
 function zodErrorToIssues(err) {
@@ -851,6 +1260,8 @@ function zodErrorToIssues(err) {
 }
 
 // src/parse/parse-import.ts
+var MAX_JSON_BYTES = 5 * 1024 * 1024;
+var MAX_JSON_OBJECT_DEPTH = 200;
 function parseJsonSafe(json) {
   try {
     return { ok: true, value: JSON.parse(json) };
@@ -858,11 +1269,36 @@ function parseJsonSafe(json) {
     return { ok: false, err: e.message };
   }
 }
+function exceedsObjectDepth(value, limit) {
+  const stack = [{ val: value, depth: 1 }];
+  while (stack.length > 0) {
+    const { val, depth } = stack.pop();
+    if (depth > limit) return true;
+    if (typeof val !== "object" || val === null) continue;
+    const children = Array.isArray(val) ? val : Object.values(val);
+    for (const child of children) {
+      if (typeof child === "object" && child !== null) {
+        stack.push({ val: child, depth: depth + 1 });
+      }
+    }
+  }
+  return false;
+}
 function parseImportPayload(json, prior) {
+  if (json.length > MAX_JSON_BYTES) {
+    throw new ParseJsonError(
+      `Workflow JSON exceeds the maximum allowed size of ${MAX_JSON_BYTES / (1024 * 1024)} MB.`
+    );
+  }
   const parsed = parseJsonSafe(json);
   if (!parsed.ok) {
     throw new ParseJsonError(`Invalid JSON: ${parsed.err}`);
   }
+  if (exceedsObjectDepth(parsed.value, MAX_JSON_OBJECT_DEPTH)) {
+    throw new ParseJsonError(
+      `Workflow JSON nesting depth exceeds the maximum allowed depth of ${MAX_JSON_OBJECT_DEPTH}.`
+    );
+  }
   let aliased;
   try {
     aliased = normalizeOperatorAlias(parsed.value);
@@ -878,7 +1314,7 @@ function parseImportPayload(json, prior) {
       ]
     };
   }
-  const schemaResult = ImportPayloadSchema.safeParse(aliased);
+  const schemaResult = ImportPayloadSchema.safeParse(coerceCanonicalDefaults(aliased));
   if (!schemaResult.success) {
     return { ok: false, issues: zodErrorToIssues(schemaResult.error) };
   }
@@ -899,6 +1335,53 @@ function parseImportPayload(json, prior) {
     issues
   };
 }
+function coerceCanonicalDefaults(value) {
+  if (!isObj(value)) return value;
+  const v = value;
+  if (!Array.isArray(v["workflows"])) return value;
+  return {
+    ...v,
+    workflows: v["workflows"].map((wf) => {
+      if (!isObj(wf)) return wf;
+      const w = wf;
+      if (!isObj(w["states"])) return wf;
+      const states = w["states"];
+      const nextStates = {};
+      for (const [code, state] of Object.entries(states)) {
+        if (!isObj(state)) {
+          nextStates[code] = state;
+          continue;
+        }
+        const s = state;
+        if (!Array.isArray(s["transitions"])) {
+          nextStates[code] = state;
+          continue;
+        }
+        nextStates[code] = {
+          ...s,
+          transitions: s["transitions"].map((t) => {
+            if (!isObj(t)) return t;
+            const tx = t;
+            if (!Array.isArray(tx["processors"])) return t;
+            return {
+              ...tx,
+              processors: tx["processors"].map((p) => {
+                if (!isObj(p)) return p;
+                const proc = p;
+                if (typeof proc["type"] === "string") return p;
+                return { type: "externalized", ...proc };
+              })
+            };
+          })
+        };
+      }
+      return { ...w, states: nextStates };
+    })
+  };
+}
+function isObj(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 
 // src/parse/parse-export.ts
 function parseExportPayload(json, prior) {
@@ -1049,7 +1532,11 @@ function outputCriterion(c) {
         jsonPath: c.jsonPath,
         operation: c.operation
       };
-      if (c.value !== void 0) out["value"] = c.value;
+      if (c.operation === "IS_NULL" || c.operation === "NOT_NULL") {
+        out["value"] = null;
+      } else if (c.value !== void 0) {
+        out["value"] = c.value;
+      }
       return out;
     }
     case "group":
@@ -1075,7 +1562,11 @@ function outputCriterion(c) {
         field: c.field,
         operation: c.operation
       };
-      if (c.value !== void 0) out["value"] = c.value;
+      if (c.operation === "IS_NULL" || c.operation === "NOT_NULL") {
+        out["value"] = null;
+      } else if (c.value !== void 0) {
+        out["value"] = c.value;
+      }
       return out;
     }
     case "array":
@@ -1108,8 +1599,9 @@ function outputExternalizedProcessor(p) {
     type: "externalized",
     name: p.name
   };
-  if (p.executionMode !== void 0 && p.executionMode !== "ASYNC_NEW_TX") {
-    out["executionMode"] = p.executionMode;
+  out["executionMode"] = p.executionMode ?? "ASYNC_NEW_TX";
+  if ("startNewTxOnDispatch" in p && p.startNewTxOnDispatch !== void 0) {
+    out["startNewTxOnDispatch"] = p.startNewTxOnDispatch;
   }
   if (p.config !== void 0) {
     const cfg = outputExternalizedConfig(p.config);
@@ -1304,45 +1796,6 @@ function walkPath(root, path) {
   return null;
 }
 
-// src/identity/id-for.ts
-function idFor2(meta, ref) {
-  switch (ref.kind) {
-    case "workflow":
-      return meta.ids.workflows[ref.workflow] ?? null;
-    case "state": {
-      for (const [uuid, ptr] of Object.entries(meta.ids.states)) {
-        if (ptr.workflow === ref.workflow && ptr.state === ref.state) return uuid;
-      }
-      return null;
-    }
-    case "transition": {
-      const matches = [];
-      for (const [uuid, ptr] of Object.entries(meta.ids.transitions)) {
-        if (ptr.workflow === ref.workflow && ptr.state === ref.state) {
-          matches.push(uuid);
-        }
-      }
-      return matches[ref.ordinal] ?? null;
-    }
-    case "processor": {
-      const matches = [];
-      for (const [uuid, ptr] of Object.entries(meta.ids.processors)) {
-        if (ptr.transitionUuid === ref.transitionUuid) matches.push(uuid);
-      }
-      return matches[ref.ordinal] ?? null;
-    }
-    case "criterion": {
-      const target = JSON.stringify(ref.path);
-      for (const [uuid, ptr] of Object.entries(meta.ids.criteria)) {
-        if (JSON.stringify(ptr.host) === JSON.stringify(ref.host) && JSON.stringify(ptr.path) === target) {
-          return uuid;
-        }
-      }
-      return null;
-    }
-  }
-}
-
 // src/validate/index.ts
 function validateImportSchema(raw) {
   const parsed = ImportPayloadSchema.safeParse(raw);
@@ -1362,9 +1815,13 @@ function validateSession(session) {
 // src/patch/apply.ts
 import { produce } from "immer";
 function applyPatch(doc, patch) {
-  if (patch.op === "setEdgeAnchors") {
-    return applySetEdgeAnchors(doc, patch);
-  }
+  if (patch.op === "setEdgeAnchors") return applySetEdgeAnchors(doc, patch);
+  if (patch.op === "setNodePosition") return applySetNodePosition(doc, patch);
+  if (patch.op === "removeNodePosition") return applyRemoveNodePosition(doc, patch);
+  if (patch.op === "resetLayout") return applyResetLayout(doc, patch);
+  if (patch.op === "addComment") return applyAddComment(doc, patch);
+  if (patch.op === "updateComment") return applyUpdateComment(doc, patch);
+  if (patch.op === "removeComment") return applyRemoveComment(doc, patch);
   const nextSession = produce(doc.session, (d) => {
     const draft = d;
     switch (patch.op) {
@@ -1410,6 +1867,11 @@ function applyPatch(doc, patch) {
       case "renameState": {
         const wf = draft.workflows.find((w) => w.name === patch.workflow);
         if (!wf) return;
+        if (patch.to !== patch.from && patch.to in wf.states) {
+          throw new PatchConflictError(
+            `State "${patch.to}" already exists in workflow "${patch.workflow}"`
+          );
+        }
         renameStateCascading(wf, patch.from, patch.to);
         return;
       }
@@ -1457,6 +1919,23 @@ function applyPatch(doc, patch) {
         state.transitions.splice(patch.toIndex, 0, item);
         return;
       }
+      case "moveTransitionSource": {
+        const wf = draft.workflows.find((w) => w.name === patch.workflow);
+        if (!wf) return;
+        const fromState = wf.states[patch.fromState];
+        const toState = wf.states[patch.toState];
+        if (!fromState || !toState) return;
+        const idx = fromState.transitions.findIndex((t) => t.name === patch.transitionName);
+        if (idx < 0) return;
+        if (patch.fromState !== patch.toState && toState.transitions.some((t) => t.name === patch.transitionName)) {
+          throw new PatchConflictError(
+            `Transition "${patch.transitionName}" already exists in state "${patch.toState}"`
+          );
+        }
+        const [transition] = fromState.transitions.splice(idx, 1);
+        if (transition) toState.transitions.push(transition);
+        return;
+      }
       case "addProcessor": {
         const loc = locateTransition(doc, patch.transitionUuid);
         if (!loc) return;
@@ -1539,9 +2018,11 @@ function applyPatch(doc, patch) {
     }
   });
   const nextMeta = assignSyntheticIds(nextSession, doc.meta);
+  preserveMovedTransitionUuid(doc, patch, nextSession, nextMeta);
+  const cleanedWorkflowUi = cleanupWorkflowUi(nextMeta.workflowUi, nextSession, nextMeta);
   return {
     session: nextSession,
-    meta: { ...nextMeta, revision: doc.meta.revision + 1 }
+    meta: { ...nextMeta, workflowUi: cleanedWorkflowUi, revision: doc.meta.revision + 1 }
   };
 }
 function applyPatches(doc, patches) {
@@ -1574,6 +2055,124 @@ function applySetEdgeAnchors(doc, patch) {
     }
   };
 }
+function applySetNodePosition(doc, patch) {
+  const workflowUi = { ...doc.meta.workflowUi };
+  const current = workflowUi[patch.workflow] ?? {};
+  const nodes = { ...current.layout?.nodes ?? {} };
+  nodes[patch.stateCode] = { x: patch.x, y: patch.y, pinned: patch.pinned ?? true };
+  workflowUi[patch.workflow] = { ...current, layout: { nodes } };
+  return {
+    session: doc.session,
+    meta: { ...doc.meta, workflowUi, revision: doc.meta.revision + 1 }
+  };
+}
+function applyRemoveNodePosition(doc, patch) {
+  const workflowUi = { ...doc.meta.workflowUi };
+  const current = workflowUi[patch.workflow] ?? {};
+  const nodes = { ...current.layout?.nodes ?? {} };
+  delete nodes[patch.stateCode];
+  workflowUi[patch.workflow] = {
+    ...current,
+    layout: Object.keys(nodes).length > 0 ? { nodes } : void 0
+  };
+  return {
+    session: doc.session,
+    meta: { ...doc.meta, workflowUi, revision: doc.meta.revision + 1 }
+  };
+}
+function applyResetLayout(doc, patch) {
+  const workflowUi = { ...doc.meta.workflowUi };
+  const current = workflowUi[patch.workflow] ?? {};
+  workflowUi[patch.workflow] = { ...current, layout: void 0 };
+  return {
+    session: doc.session,
+    meta: { ...doc.meta, workflowUi, revision: doc.meta.revision + 1 }
+  };
+}
+function applyAddComment(doc, patch) {
+  const workflowUi = { ...doc.meta.workflowUi };
+  const current = workflowUi[patch.workflow] ?? {};
+  const comments = { ...current.comments ?? {}, [patch.comment.id]: patch.comment };
+  workflowUi[patch.workflow] = { ...current, comments };
+  return {
+    session: doc.session,
+    meta: { ...doc.meta, workflowUi, revision: doc.meta.revision + 1 }
+  };
+}
+function applyUpdateComment(doc, patch) {
+  const workflowUi = { ...doc.meta.workflowUi };
+  const current = workflowUi[patch.workflow] ?? {};
+  const existing = current.comments?.[patch.commentId];
+  if (!existing) return { ...doc, meta: { ...doc.meta, revision: doc.meta.revision + 1 } };
+  const updated = { ...existing, ...patch.updates, id: existing.id };
+  const comments = { ...current.comments ?? {}, [patch.commentId]: updated };
+  workflowUi[patch.workflow] = { ...current, comments };
+  return {
+    session: doc.session,
+    meta: { ...doc.meta, workflowUi, revision: doc.meta.revision + 1 }
+  };
+}
+function applyRemoveComment(doc, patch) {
+  const workflowUi = { ...doc.meta.workflowUi };
+  const current = workflowUi[patch.workflow] ?? {};
+  const comments = { ...current.comments ?? {} };
+  delete comments[patch.commentId];
+  workflowUi[patch.workflow] = {
+    ...current,
+    comments: Object.keys(comments).length > 0 ? comments : void 0
+  };
+  return {
+    session: doc.session,
+    meta: { ...doc.meta, workflowUi, revision: doc.meta.revision + 1 }
+  };
+}
+function preserveMovedTransitionUuid(priorDoc, patch, nextSession, nextMeta) {
+  if (patch.op !== "moveTransitionSource") return;
+  const oldUuid = transitionUuidByName(
+    priorDoc,
+    patch.workflow,
+    patch.fromState,
+    patch.transitionName
+  );
+  if (!oldUuid) return;
+  const newUuid = transitionUuidByNameInSession(
+    nextSession,
+    nextMeta,
+    patch.workflow,
+    patch.toState,
+    patch.transitionName
+  );
+  if (!newUuid || newUuid === oldUuid) return;
+  const newPtr = nextMeta.ids.transitions[newUuid];
+  if (!newPtr) return;
+  delete nextMeta.ids.transitions[newUuid];
+  nextMeta.ids.transitions[oldUuid] = {
+    ...newPtr,
+    transitionUuid: oldUuid
+  };
+  for (const processorPtr of Object.values(nextMeta.ids.processors)) {
+    if (processorPtr.transitionUuid === newUuid) {
+      processorPtr.transitionUuid = oldUuid;
+    }
+  }
+  for (const criterionPtr of Object.values(nextMeta.ids.criteria)) {
+    const host = criterionPtr.host;
+    if ((host.kind === "transition" || host.kind === "processorConfig") && host.transitionUuid === newUuid) {
+      host.transitionUuid = oldUuid;
+    }
+  }
+}
+function transitionUuidByName(doc, workflow, state, transitionName) {
+  return transitionUuidByNameInSession(doc.session, doc.meta, workflow, state, transitionName);
+}
+function transitionUuidByNameInSession(session, meta, workflow, state, transitionName) {
+  const wf = session.workflows.find((candidate) => candidate.name === workflow);
+  const transitions = wf?.states[state]?.transitions ?? [];
+  const index = transitions.findIndex((transition) => transition.name === transitionName);
+  if (index < 0) return null;
+  const ordered = Object.entries(meta.ids.transitions).filter(([, ptr]) => ptr.workflow === workflow && ptr.state === state).map(([uuid]) => uuid);
+  return ordered[index] ?? null;
+}
 function renameStateCascading(wf, from, to) {
   if (!(from in wf.states) || from === to) return;
   wf.states[to] = wf.states[from];
@@ -1622,6 +2221,65 @@ function locateProcessor(doc, processorUuid) {
     processorIndex: pIdx
   };
 }
+function cleanupWorkflowUi(workflowUi, session, meta) {
+  const wfNames = new Set(session.workflows.map((w) => w.name));
+  const result = {};
+  const validTransitionIdsByWorkflow = /* @__PURE__ */ new Map();
+  if (meta) {
+    for (const [uuid, ptr] of Object.entries(meta.ids.transitions)) {
+      let set = validTransitionIdsByWorkflow.get(ptr.workflow);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        validTransitionIdsByWorkflow.set(ptr.workflow, set);
+      }
+      set.add(uuid);
+    }
+  }
+  for (const [wfName, ui] of Object.entries(workflowUi)) {
+    if (!wfNames.has(wfName)) continue;
+    const wf = session.workflows.find((w) => w.name === wfName);
+    const existingStates = wf ? new Set(Object.keys(wf.states)) : /* @__PURE__ */ new Set();
+    const allTransitionNames = /* @__PURE__ */ new Set();
+    if (wf) {
+      for (const state of Object.values(wf.states)) {
+        for (const t of state.transitions) allTransitionNames.add(t.name);
+      }
+    }
+    let layout = ui.layout;
+    if (layout?.nodes) {
+      const cleanNodes = Object.fromEntries(
+        Object.entries(layout.nodes).filter(([code]) => existingStates.has(code))
+      );
+      layout = Object.keys(cleanNodes).length > 0 ? { nodes: cleanNodes } : void 0;
+    }
+    let comments = ui.comments;
+    if (comments) {
+      const cleanComments = {};
+      for (const [id, c] of Object.entries(comments)) {
+        if (c.attachedTo?.kind === "state" && !existingStates.has(c.attachedTo.stateCode)) {
+          cleanComments[id] = { ...c, attachedTo: { kind: "free" } };
+        } else if (c.attachedTo?.kind === "transition" && !allTransitionNames.has(c.attachedTo.transitionName)) {
+          cleanComments[id] = { ...c, attachedTo: { kind: "free" } };
+        } else {
+          cleanComments[id] = c;
+        }
+      }
+      comments = Object.keys(cleanComments).length > 0 ? cleanComments : void 0;
+    }
+    let edgeAnchors = ui.edgeAnchors;
+    if (edgeAnchors && meta) {
+      const validTransitionIds = validTransitionIdsByWorkflow.get(wfName) ?? /* @__PURE__ */ new Set();
+      const cleanAnchors = Object.fromEntries(
+        Object.entries(edgeAnchors).filter(
+          ([transitionUuid]) => validTransitionIds.has(transitionUuid)
+        )
+      );
+      edgeAnchors = Object.keys(cleanAnchors).length > 0 ? cleanAnchors : void 0;
+    }
+    result[wfName] = { ...ui, layout, comments, edgeAnchors };
+  }
+  return result;
+}
 function applyCriterionAtPath(container, path, criterion) {
   if (path.length === 0) return;
   let node = container;
@@ -1658,7 +2316,6 @@ function invertPatch(doc, patch) {
     case "removeWorkflow":
     case "renameWorkflow":
     case "removeState":
-    case "renameState":
     case "replaceSession":
       return { op: "replaceSession", session: cloneSession(doc) };
     case "updateWorkflowMeta": {
@@ -1673,30 +2330,19 @@ function invertPatch(doc, patch) {
     case "setInitialState": {
       const wf = findWorkflow(doc, patch.workflow);
       if (!wf) return noop();
-      return {
-        op: "setInitialState",
-        workflow: patch.workflow,
-        stateCode: wf.initialState
-      };
+      return { op: "setInitialState", workflow: patch.workflow, stateCode: wf.initialState };
     }
     case "setWorkflowCriterion": {
       const wf = findWorkflow(doc, patch.workflow);
       if (!wf) return noop();
-      return wf.criterion ? {
-        op: "setWorkflowCriterion",
-        workflow: patch.workflow,
-        criterion: cloneCriterion(wf.criterion)
-      } : { op: "setWorkflowCriterion", workflow: patch.workflow };
+      return wf.criterion ? { op: "setWorkflowCriterion", workflow: patch.workflow, criterion: cloneCriterion(wf.criterion) } : { op: "setWorkflowCriterion", workflow: patch.workflow };
     }
     case "addState":
-      return {
-        op: "removeState",
-        workflow: patch.workflow,
-        stateCode: patch.stateCode
-      };
-    case "addTransition": {
+      return { op: "removeState", workflow: patch.workflow, stateCode: patch.stateCode };
+    case "renameState":
+      return { op: "renameState", workflow: patch.workflow, from: patch.to, to: patch.from };
+    case "addTransition":
       return { op: "replaceSession", session: cloneSession(doc) };
-    }
     case "updateTransition": {
       const t = findTransition(doc, patch.transitionUuid);
       if (!t) return noop();
@@ -1704,15 +2350,48 @@ function invertPatch(doc, patch) {
       for (const key of Object.keys(patch.updates)) {
         prior[key] = t[key];
       }
+      return { op: "updateTransition", transitionUuid: patch.transitionUuid, updates: prior };
+    }
+    case "removeTransition": {
+      const loc = locateTransition2(doc, patch.transitionUuid);
+      if (!loc) return noop();
+      const wf = findWorkflow(doc, loc.workflow);
+      const state = wf?.states[loc.state];
+      const t = state?.transitions[loc.index];
+      if (!t) return noop();
       return {
-        op: "updateTransition",
-        transitionUuid: patch.transitionUuid,
-        updates: prior
+        op: "addTransition",
+        workflow: loc.workflow,
+        fromState: loc.state,
+        transition: structuredClone(t)
       };
     }
-    case "removeTransition":
-    case "reorderTransition":
-      return { op: "replaceSession", session: cloneSession(doc) };
+    case "reorderTransition": {
+      const loc = locateTransition2(doc, patch.transitionUuid);
+      if (!loc) return noop();
+      const orderedForState = [];
+      for (const [uuid, p] of Object.entries(doc.meta.ids.transitions)) {
+        if (p.workflow === patch.workflow && p.state === patch.fromState) {
+          orderedForState.push(uuid);
+        }
+      }
+      const uuidAtTarget = orderedForState[patch.toIndex] ?? patch.transitionUuid;
+      return {
+        op: "reorderTransition",
+        workflow: patch.workflow,
+        fromState: patch.fromState,
+        transitionUuid: uuidAtTarget,
+        toIndex: loc.index
+      };
+    }
+    case "moveTransitionSource":
+      return {
+        op: "moveTransitionSource",
+        workflow: patch.workflow,
+        fromState: patch.toState,
+        toState: patch.fromState,
+        transitionName: patch.transitionName
+      };
     case "addProcessor":
       return { op: "replaceSession", session: cloneSession(doc) };
     case "updateProcessor": {
@@ -1722,23 +2401,43 @@ function invertPatch(doc, patch) {
       for (const key of Object.keys(patch.updates)) {
         prior[key] = p[key];
       }
+      return { op: "updateProcessor", processorUuid: patch.processorUuid, updates: prior };
+    }
+    case "removeProcessor": {
+      const ptr = doc.meta.ids.processors[patch.processorUuid];
+      if (!ptr) return noop();
+      const procLoc = locateProcessor2(doc, patch.processorUuid);
+      if (!procLoc) return noop();
+      const wf = findWorkflow(doc, procLoc.workflow);
+      const state = wf?.states[procLoc.state];
+      const t = state?.transitions[procLoc.transitionIndex];
+      const p = t?.processors?.[procLoc.processorIndex];
+      if (!p) return noop();
       return {
-        op: "updateProcessor",
-        processorUuid: patch.processorUuid,
-        updates: prior
+        op: "addProcessor",
+        transitionUuid: ptr.transitionUuid,
+        processor: structuredClone(p),
+        index: procLoc.processorIndex
+      };
+    }
+    case "reorderProcessor": {
+      const procLoc = locateProcessor2(doc, patch.processorUuid);
+      if (!procLoc) return noop();
+      const orderedForTransition = [];
+      for (const [uuid, p] of Object.entries(doc.meta.ids.processors)) {
+        if (p.transitionUuid === patch.transitionUuid) orderedForTransition.push(uuid);
+      }
+      const uuidAtTarget = orderedForTransition[patch.toIndex] ?? patch.processorUuid;
+      return {
+        op: "reorderProcessor",
+        transitionUuid: patch.transitionUuid,
+        processorUuid: uuidAtTarget,
+        toIndex: procLoc.processorIndex
       };
     }
-    case "removeProcessor":
-    case "reorderProcessor":
-      return { op: "replaceSession", session: cloneSession(doc) };
     case "setCriterion": {
       const prior = readCriterionAt(doc, patch.host, patch.path);
-      return prior === void 0 ? { op: "setCriterion", host: patch.host, path: patch.path } : {
-        op: "setCriterion",
-        host: patch.host,
-        path: patch.path,
-        criterion: cloneCriterion(prior)
-      };
+      return prior === void 0 ? { op: "setCriterion", host: patch.host, path: patch.path } : { op: "setCriterion", host: patch.host, path: patch.path, criterion: cloneCriterion(prior) };
     }
     case "setImportMode":
       return { op: "setImportMode", mode: doc.session.importMode };
@@ -1754,6 +2453,36 @@ function invertPatch(doc, patch) {
         anchors: prior ? { ...prior } : null
       };
     }
+    case "setNodePosition": {
+      const prior = doc.meta.workflowUi[patch.workflow]?.layout?.nodes?.[patch.stateCode];
+      if (!prior) {
+        return { op: "removeNodePosition", workflow: patch.workflow, stateCode: patch.stateCode };
+      }
+      return { op: "setNodePosition", workflow: patch.workflow, stateCode: patch.stateCode, ...prior };
+    }
+    case "removeNodePosition": {
+      const prior = doc.meta.workflowUi[patch.workflow]?.layout?.nodes?.[patch.stateCode];
+      if (!prior) return noop();
+      return { op: "setNodePosition", workflow: patch.workflow, stateCode: patch.stateCode, ...prior };
+    }
+    case "resetLayout":
+      return noop();
+    case "addComment":
+      return { op: "removeComment", workflow: patch.workflow, commentId: patch.comment.id };
+    case "updateComment": {
+      const prior = doc.meta.workflowUi[patch.workflow]?.comments?.[patch.commentId];
+      if (!prior) return noop();
+      const priorUpdates = {};
+      for (const key of Object.keys(patch.updates)) {
+        priorUpdates[key] = prior[key];
+      }
+      return { op: "updateComment", workflow: patch.workflow, commentId: patch.commentId, updates: priorUpdates };
+    }
+    case "removeComment": {
+      const prior = doc.meta.workflowUi[patch.workflow]?.comments?.[patch.commentId];
+      if (!prior) return noop();
+      return { op: "addComment", workflow: patch.workflow, comment: structuredClone(prior) };
+    }
   }
 }
 function noop() {
@@ -1762,30 +2491,42 @@ function noop() {
 function findWorkflow(doc, name) {
   return doc.session.workflows.find((w) => w.name === name);
 }
-function findTransition(doc, transitionUuid) {
+function locateTransition2(doc, transitionUuid) {
   const ptr = doc.meta.ids.transitions[transitionUuid];
-  if (!ptr) return void 0;
-  const wf = findWorkflow(doc, ptr.workflow);
-  const state = wf?.states[ptr.state];
-  if (!state) return void 0;
+  if (!ptr) return null;
   const ordered = [];
   for (const [uuid, p] of Object.entries(doc.meta.ids.transitions)) {
     if (p.workflow === ptr.workflow && p.state === ptr.state) ordered.push(uuid);
   }
   const idx = ordered.indexOf(transitionUuid);
-  return state.transitions[idx];
+  if (idx < 0) return null;
+  return { workflow: ptr.workflow, state: ptr.state, index: idx };
 }
-function findProcessor(doc, processorUuid) {
+function locateProcessor2(doc, processorUuid) {
   const ptr = doc.meta.ids.processors[processorUuid];
-  if (!ptr) return void 0;
-  const t = findTransition(doc, ptr.transitionUuid);
-  if (!t?.processors) return void 0;
+  if (!ptr) return null;
+  const tLoc = locateTransition2(doc, ptr.transitionUuid);
+  if (!tLoc) return null;
   const ordered = [];
   for (const [uuid, p] of Object.entries(doc.meta.ids.processors)) {
     if (p.transitionUuid === ptr.transitionUuid) ordered.push(uuid);
   }
-  const idx = ordered.indexOf(processorUuid);
-  return t.processors[idx];
+  const pIdx = ordered.indexOf(processorUuid);
+  if (pIdx < 0) return null;
+  return { workflow: tLoc.workflow, state: tLoc.state, transitionIndex: tLoc.index, processorIndex: pIdx };
+}
+function findTransition(doc, transitionUuid) {
+  const loc = locateTransition2(doc, transitionUuid);
+  if (!loc) return void 0;
+  const wf = findWorkflow(doc, loc.workflow);
+  return wf?.states[loc.state]?.transitions[loc.index];
+}
+function findProcessor(doc, processorUuid) {
+  const loc = locateProcessor2(doc, processorUuid);
+  if (!loc) return void 0;
+  const wf = findWorkflow(doc, loc.workflow);
+  const t = wf?.states[loc.state]?.transitions[loc.transitionIndex];
+  return t?.processors?.[loc.processorIndex];
 }
 function readCriterionAt(doc, host, path) {
   const wf = findWorkflow(doc, host.workflow);
@@ -1820,6 +2561,26 @@ function cloneCriterion(c) {
   return structuredClone(c);
 }
 
+// src/patch/transaction.ts
+function applyTransaction(doc, tx) {
+  return tx.patches.reduce((d, p) => applyPatch(d, p), doc);
+}
+function invertTransaction(doc, tx) {
+  if (tx.inverses.length > 0) {
+    return {
+      summary: `Undo: ${tx.summary}`,
+      patches: tx.inverses,
+      inverses: tx.patches
+    };
+  }
+  const computed = tx.patches.map((p) => invertPatch(doc, p)).reverse();
+  return {
+    summary: `Undo: ${tx.summary}`,
+    patches: computed,
+    inverses: tx.patches
+  };
+}
+
 // src/migrate/registry.ts
 var registry = [];
 function registerMigration(entry) {
@@ -1857,8 +2618,59 @@ function migrateSession(session, from, to) {
   return path.reduce((s, entry) => entry.migrate(s), session);
 }
 registerMigration({ from: "1.0", to: "1.0", migrate: (s) => s });
+
+// src/criteria/describe.ts
+var OPERATOR_SYMBOL = {
+  EQUALS: "=",
+  NOT_EQUAL: "\u2260",
+  GREATER_THAN: ">",
+  LESS_THAN: "<",
+  GREATER_OR_EQUAL: "\u2265",
+  LESS_OR_EQUAL: "\u2264",
+  IEQUALS: "=",
+  INOT_EQUAL: "\u2260"
+};
+function describeCriterion(c) {
+  switch (c.type) {
+    case "simple":
+      return describeBinary(c.jsonPath, c.operation, c.value);
+    case "group": {
+      const n = c.conditions.length;
+      return `${c.operator} (${n} condition${n === 1 ? "" : "s"})`;
+    }
+    case "function":
+      return `Function: ${c.function.name || "<unnamed>"}`;
+    case "lifecycle":
+      return describeBinary(c.field, c.operation, c.value);
+    case "array": {
+      const n = c.value.length;
+      return `${c.jsonPath} ${c.operation} [${n} value${n === 1 ? "" : "s"}]`;
+    }
+  }
+}
+function describeBinary(lhs, op, value) {
+  if (op === "IS_NULL") return `${lhs} IS NULL`;
+  if (op === "NOT_NULL") return `${lhs} IS NOT NULL`;
+  if (op === "IS_CHANGED") return `${lhs} CHANGED`;
+  if (op === "IS_UNCHANGED") return `${lhs} UNCHANGED`;
+  if (op === "BETWEEN" || op === "BETWEEN_INCLUSIVE") {
+    const inclusive = op === "BETWEEN_INCLUSIVE";
+    if (Array.isArray(value) && value.length === 2) {
+      return `${lhs} \u2208 ${inclusive ? "[" : "("}${formatValue(value[0])}, ${formatValue(value[1])}${inclusive ? "]" : ")"}`;
+    }
+    return `${lhs} ${op} ${formatValue(value)}`;
+  }
+  const symbol = OPERATOR_SYMBOL[op] ?? op;
+  return `${lhs} ${symbol} ${formatValue(value)}`;
+}
+function formatValue(v) {
+  if (v === void 0) return "?";
+  if (typeof v === "string") return JSON.stringify(v);
+  return JSON.stringify(v);
+}
 export {
   ArrayCriterionSchema,
+  CRITERION_DEPTH_WARNING_THRESHOLD,
   CriterionSchema,
   ExecutionModeSchema,
   ExportPayloadSchema,
@@ -1868,26 +2680,38 @@ export {
   GroupCriterionSchema,
   ImportPayloadSchema,
   LifecycleCriterionSchema,
+  MAX_CRITERION_DEPTH,
+  MAX_JSON_BYTES,
+  MAX_JSON_OBJECT_DEPTH,
   NAME_REGEX,
   NameSchema,
+  OPERATOR_GROUPS,
   OPERATOR_TYPES,
+  OPERATOR_VALUE_SHAPE,
   OperatorEnum,
   ParseJsonError,
+  PatchConflictError,
   ProcessorSchema,
+  SUPPORTED_GROUP_OPERATORS,
+  SUPPORTED_SIMPLE_OPERATORS,
   ScheduledProcessorSchema,
   SchemaError,
   SimpleCriterionSchema,
   StateSchema,
   TransitionSchema,
+  UNSUPPORTED_OPERATORS,
   WorkflowApiConflictError,
   WorkflowApiTransportError,
   WorkflowSchema,
   applyPatch,
   applyPatches,
+  applyTransaction,
   assignSyntheticIds,
+  describeCriterion,
   findMigrationPath,
-  idFor2 as idFor,
+  idFor,
   invertPatch,
+  invertTransaction,
   listMigrations,
   lookupById,
   migrateSession,
@@ -1913,6 +2737,7 @@ export {
   validateAll,
   validateExportSchema,
   validateImportSchema,
+  validateJsonPathSubset,
   validateSemantics,
   validateSession,
   zodErrorToIssues