@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/dist/modules/workflows/data/validators.js

@@ -1,33 +1,51 @@
 import { z } from "zod";
+import { conditionExpressionSchema } from "@open-mercato/core/modules/business_rules/data/validators";
+import { validateConditionExpressionForApi } from "@open-mercato/core/modules/business_rules/lib/payload-validation";
 import { parseDuration } from "../lib/duration.js";
+import { excludeNonNormalTransitions } from "../lib/route-kinds.js";
+import { WORKFLOW_RUN_OUTCOMES } from "../lib/run-outcome.js";
+import {
+  WORKFLOW_START_FIXTURES_MAX_CHARS,
+  WORKFLOW_START_FIXTURES_MAX_COUNT,
+  WORKFLOW_START_FIXTURE_NAME_MAX
+} from "../lib/start-fixtures.js";
+import "../lib/activity-registry-bootstrap.js";
+import { activityTypeIds } from "../lib/activity-registry.js";
+import {
+  DURATION_ERROR,
+  UNTIL_ERROR,
+  UNTIL_PAST_ERROR,
+  invokeAgentConfigSchema,
+  isFutureIsoDateString,
+  isValidDurationString,
+  isValidIsoDateString
+} from "./activity-config-schemas.js";
+import {
+  taskDeadlineSchema,
+  taskPrioritySchema,
+  taskReminderSchema
+} from "./task-primitives.js";
+import {
+  isValidDurationString as isValidDurationString2,
+  isValidIsoDateString as isValidIsoDateString2,
+  isFutureIsoDateString as isFutureIsoDateString2,
+  callApiConfigSchema,
+  callWebhookConfigSchema,
+  sendEmailConfigSchema,
+  emitEventConfigSchema,
+  updateEntityConfigSchema,
+  executeFunctionConfigSchema,
+  invokeAgentConfigSchema as invokeAgentConfigSchema2,
+  setVariableAssignmentSchema,
+  setVariableConfigSchema,
+  waitConfigSchema
+} from "./activity-config-schemas.js";
+import {
+  taskPrioritySchema as taskPrioritySchema2,
+  taskDeadlineSchema as taskDeadlineSchema2,
+  taskReminderSchema as taskReminderSchema2
+} from "./task-primitives.js";
 const uuid = z.uuid();
-const containsTemplate = (value) => value.includes("{{");
-function isValidDurationString(value) {
-  if (typeof value !== "string" || value.length === 0) return false;
-  if (containsTemplate(value)) return true;
-  try {
-    const ms = parseDuration(value);
-    return Number.isFinite(ms) && ms > 0;
-  } catch {
-    return false;
-  }
-}
-function isValidIsoDateString(value) {
-  if (typeof value !== "string" || value.length === 0) return false;
-  if (containsTemplate(value)) return true;
-  const d = new Date(value);
-  return !Number.isNaN(d.getTime());
-}
-function isFutureIsoDateString(value) {
-  if (typeof value !== "string" || value.length === 0) return false;
-  if (containsTemplate(value)) return true;
-  const d = new Date(value);
-  if (Number.isNaN(d.getTime())) return false;
-  return d.getTime() > Date.now();
-}
-const DURATION_ERROR = "Invalid duration. Use ISO 8601 (e.g., PT5M, PT1H, P1D) or simple format (5m, 1h, 3d)";
-const UNTIL_ERROR = 'Invalid "until". Provide an ISO 8601 datetime string';
-const UNTIL_PAST_ERROR = '"until" must be a future datetime';
 const workflowStepTypeSchema = z.enum([
   "START",
   "END",
@@ -37,7 +55,10 @@ const workflowStepTypeSchema = z.enum([
   "PARALLEL_JOIN",
   "SUB_WORKFLOW",
   "WAIT_FOR_SIGNAL",
-  "WAIT_FOR_TIMER"
+  "WAIT_FOR_TIMER",
+  "WAIT_FOR_CONDITION",
+  "IF_ELSE",
+  "SWITCH"
 ]);
 const workflowInstanceStatusSchema = z.enum([
   "RUNNING",
@@ -50,6 +71,9 @@ const workflowInstanceStatusSchema = z.enum([
   "WAITING_FOR_ACTIVITIES",
   "FORKED"
 ]);
+const workflowRunOutcomeSchema = z.enum(
+  WORKFLOW_RUN_OUTCOMES
+);
 const workflowBranchInstanceStatusSchema = z.enum([
   "ACTIVE",
   "PAUSED",
@@ -74,26 +98,54 @@ const userTaskStatusSchema = z.enum([
   "ESCALATED"
 ]);
 const transitionTriggerSchema = z.enum(["auto", "manual", "signal", "timer"]);
-const activityTypeSchema = z.enum([
-  "SEND_EMAIL",
-  "CALL_API",
-  "UPDATE_ENTITY",
-  "EMIT_EVENT",
-  "CALL_WEBHOOK",
-  "EXECUTE_FUNCTION",
-  "WAIT"
-]);
+const activityTypeSchema = z.enum(activityTypeIds());
 const escalationTriggerSchema = z.enum(["sla_breach", "no_progress", "custom"]);
 const escalationActionSchema = z.enum(["reassign", "notify", "escalate"]);
+const taskLocalizedStringSchema = z.union([
+  z.string(),
+  z.record(z.string(), z.string())
+]);
+const taskEntityBindingSchema = z.object({
+  entityType: z.string().min(1),
+  idPath: z.string().min(1),
+  label: taskLocalizedStringSchema.optional()
+});
+const taskOnBreachSchema = z.object({
+  action: z.enum(["notify", "reassign", "route"]),
+  reassignTo: z.string().optional(),
+  transitionId: z.string().optional()
+});
+const taskDecisionSchema = z.object({
+  id: z.string().min(1),
+  label: taskLocalizedStringSchema,
+  transitionId: z.string().min(1),
+  style: z.enum(["primary", "secondary", "destructive"]).optional()
+});
+const userTaskAssigneeKindSchema = z.enum(["user", "customer"]);
 const userTaskConfigSchema = z.object({
   // Support both custom fields array format and JSON Schema format
   formSchema: z.union([
-    // Custom format with fields array
+    // Custom format with fields array.
+    //
+    // `label` is OPTIONAL because every consumer already treats it that way:
+    // `lib/task-form-schema.ts` — the single pure mapper behind both form
+    // validation and rendering — declares `label?: string` and resolves
+    // `title: field.label ?? field.name`, and the editor's own list renders
+    // `field.label || field.name`. Requiring it here made the contract
+    // stricter than the code reading it, which rejected definitions the
+    // engine would have run: the AI draft schema (`lib/ai-authoring.ts`)
+    // and the `create_definition` MCP tool both emit an optional label, so
+    // a generated definition could 400 on a field the runtime renders fine.
+    //
+    // This is a WIDENING change — payloads rejected before are accepted now,
+    // and nothing previously accepted changes — so it needs no deprecation
+    // window. A missing label is an authoring-quality issue, and this module
+    // surfaces those through the Problems panel rather than a hard 400.
     z.object({
       fields: z.array(z.object({
         name: z.string().min(1),
         type: z.string().min(1),
-        label: z.string().min(1),
+        label: z.string().min(1).optional(),
         required: z.boolean().optional(),
         options: z.array(z.any()).optional()
       }))
@@ -109,6 +161,31 @@ const userTaskConfigSchema = z.object({
     z.string(),
     z.array(z.string())
   ]).optional(),
+  // Role queue the task is offered to when no individual assignee is set. The
+  // editor has always written this key (`lib/graph-utils.ts`) and the engine has
+  // always read it (`lib/step-handler.ts`), but it was undeclared here — zod
+  // strips unknown keys and the definition PUT persists the PARSED value, so
+  // authored role assignment was silently discarded on every save.
+  assignedToRoles: z.array(z.string()).optional(),
+  /**
+   * Which principal namespace `assignedTo` names (design §7.1).
+   *
+   * `'customer'` addresses the task to a PORTAL principal — the resolved id is a
+   * `CustomerUser.id`, the row is written with `assignee_kind = 'customer'`, and
+   * only `/api/workflows/portal/tasks*` can see or complete it. It is honoured
+   * only when an individual assignee resolves, and it forces `assignedToRoles`
+   * to null: portal roles are a different namespace and a portal principal
+   * cannot claim from a backoffice queue.
+   *
+   * Absent means `'user'`, which is what every definition authored before this
+   * key existed has always meant.
+   */
+  assigneeKind: userTaskAssigneeKindSchema.optional(),
+  // Renderer key for an externally registered task form. Same round-trip as
+  // `assignedToRoles`: written by the editor, previously stripped on save.
+  formKey: z.string().optional(),
+  // Actions offered on the task surface (editor default: complete + cancel).
+  allowedActions: z.array(z.string()).optional(),
   assignmentRule: z.string().optional(),
   // Business rule ID
   slaDuration: z.string().optional(),
@@ -118,7 +195,26 @@ const userTaskConfigSchema = z.object({
     action: escalationActionSchema,
     escalateTo: z.string().optional(),
     notifyUsers: z.array(z.string()).optional()
-  })).optional()
+  })).optional(),
+  // --------------------------------------------------------------------------
+  // Task inspector vocabulary (spec §6.1). Every key below is OPTIONAL and
+  // additive: a config declaring none of them parses to exactly what it parsed
+  // to before, and the engine reads it exactly as it did before. A regression
+  // test in `lib/__tests__/user-task-config.test.ts` pins that byte-for-byte.
+  // --------------------------------------------------------------------------
+  // "What": rich instructions shown to the assignee, variable pills included.
+  instructions: taskLocalizedStringSchema.optional(),
+  // "About what": the records this task is about.
+  entityBindings: z.array(taskEntityBindingSchema).optional(),
+  // "When": priority, deadline, reminders, and what happens on breach.
+  priority: taskPrioritySchema.optional(),
+  deadline: taskDeadlineSchema.optional(),
+  reminders: z.array(taskReminderSchema).optional(),
+  onBreach: taskOnBreachSchema.optional(),
+  // "Decisions": buttons bound 1:1 to outgoing routes, plus the subset of form
+  // fields the assignee may edit before deciding.
+  decisions: z.array(taskDecisionSchema).optional(),
+  editablePrefilled: z.array(z.string()).optional()
 });
 const subWorkflowConfigSchema = z.object({
   subWorkflowId: z.string().min(1, "Sub-workflow ID is required"),
@@ -127,19 +223,17 @@ const subWorkflowConfigSchema = z.object({
   outputMapping: z.record(z.string(), z.string()).optional(),
   timeoutMs: z.number().int().positive().optional()
 });
-const callApiConfigSchema = z.object({
-  endpoint: z.string().min(1, "API endpoint is required"),
-  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).default("GET"),
-  headers: z.record(z.string(), z.string()).optional(),
-  body: z.any().optional(),
-  validateTenantMatch: z.boolean().default(true).optional(),
-  timeout: z.number().int().positive().optional()
+const portFieldTypeSchema = z.enum(["text", "number", "boolean", "select", "date"]);
+const portFieldSchema = z.object({
+  name: z.string().min(1).max(100).regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "Port name must start with a letter and contain only letters, numbers, and underscores"),
+  type: portFieldTypeSchema,
+  label: z.string().min(1).max(255),
+  required: z.boolean().optional().default(false),
+  options: z.array(z.string()).optional()
 });
-const callWebhookConfigSchema = z.object({
-  url: z.string().min(1, "Webhook URL is required"),
-  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("POST"),
-  headers: z.record(z.string(), z.string()).optional(),
-  body: z.any().optional()
+const workflowIoContractSchema = z.object({
+  inputs: z.array(portFieldSchema).optional(),
+  outputs: z.array(portFieldSchema).optional()
 });
 const retryPolicySchema = z.object({
   maxAttempts: z.number().int().min(1).max(10),
@@ -202,6 +296,19 @@ const activityDefinitionSchema = z.object({
       }
     }
   }
+  if (activity.activityType === "INVOKE_AGENT") {
+    const parsed = invokeAgentConfigSchema.safeParse(activity.config || {});
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["config", ...issue.path],
+          message: issue.message
+        });
+      }
+    }
+    return;
+  }
   if (activity.activityType !== "WAIT") return;
   const config = activity.config || {};
   const hasDuration = config.duration != null && config.duration !== "";
@@ -253,6 +360,83 @@ const startPreConditionSchema = z.object({
   validationMessage: localizedMessageSchema.optional()
   // Optional localized error messages
 });
+const CONDITION_POLL_INTERVAL_MIN_MS = 5e3;
+const CONDITION_POLL_INTERVAL_MAX_MS = 36e5;
+const CONDITION_REQUIRED_ERROR = 'WAIT_FOR_CONDITION step requires a "condition" expression';
+const CONDITION_TIMEOUT_REQUIRED_ERROR = 'WAIT_FOR_CONDITION step requires a "timeout" duration';
+const CONDITION_ON_TIMEOUT_ERROR = 'WAIT_FOR_CONDITION "onTimeout" must be "FAIL" or "CONTINUE"';
+const CONDITION_POLL_INTERVAL_RANGE_ERROR = `WAIT_FOR_CONDITION "pollIntervalMs" must be an integer between ${CONDITION_POLL_INTERVAL_MIN_MS} and ${CONDITION_POLL_INTERVAL_MAX_MS}`;
+const CONDITION_POLL_INTERVAL_EXCEEDS_TIMEOUT_ERROR = 'WAIT_FOR_CONDITION "pollIntervalMs" must not exceed "timeout" \u2014 the first poll would land after the deadline';
+function refineWaitForConditionStep(config, ctx) {
+  const condition = config.condition;
+  if (condition == null) {
+    ctx.addIssue({ code: "custom", path: ["config", "condition"], message: CONDITION_REQUIRED_ERROR });
+  } else {
+    const conditionResult = validateConditionExpressionForApi(condition);
+    if (!conditionResult.valid) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["config", "condition"],
+        message: conditionResult.error ?? CONDITION_REQUIRED_ERROR
+      });
+    }
+  }
+  const timeout = config.timeout;
+  const hasTimeout = typeof timeout === "string" && timeout.length > 0;
+  if (!hasTimeout) {
+    ctx.addIssue({ code: "custom", path: ["config", "timeout"], message: CONDITION_TIMEOUT_REQUIRED_ERROR });
+  } else if (!isValidDurationString(timeout)) {
+    ctx.addIssue({ code: "custom", path: ["config", "timeout"], message: DURATION_ERROR });
+  }
+  if (config.onTimeout != null && config.onTimeout !== "FAIL" && config.onTimeout !== "CONTINUE") {
+    ctx.addIssue({ code: "custom", path: ["config", "onTimeout"], message: CONDITION_ON_TIMEOUT_ERROR });
+  }
+  if (config.pollIntervalMs == null) return;
+  const pollIntervalMs = config.pollIntervalMs;
+  if (typeof pollIntervalMs !== "number" || !Number.isInteger(pollIntervalMs) || pollIntervalMs < CONDITION_POLL_INTERVAL_MIN_MS || pollIntervalMs > CONDITION_POLL_INTERVAL_MAX_MS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["config", "pollIntervalMs"],
+      message: CONDITION_POLL_INTERVAL_RANGE_ERROR
+    });
+    return;
+  }
+  if (hasTimeout && isValidDurationString(timeout)) {
+    const timeoutMs = parseDuration(timeout);
+    if (pollIntervalMs > timeoutMs) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["config", "pollIntervalMs"],
+        message: CONDITION_POLL_INTERVAL_EXCEEDS_TIMEOUT_ERROR
+      });
+    }
+  }
+}
+const stepErrorDirectiveSchema = z.object({
+  mode: z.enum(["fail", "continueWithFallback", "failureQueue"]),
+  fallbackValue: z.unknown().optional()
+});
+const transitionKindSchema = z.enum(["normal", "error", "slaBreach", "outcome"]);
+const workflowErrorHandlerSchema = z.object({
+  workflowId: z.string().min(1).max(100).optional(),
+  version: z.number().int().positive().optional(),
+  stepId: z.string().min(1).max(100).optional()
+}).superRefine((handler, ctx) => {
+  const forms = [handler.workflowId, handler.stepId].filter((value) => value != null && value !== "");
+  if (forms.length !== 1) {
+    ctx.addIssue({
+      code: "custom",
+      message: 'errorHandler must declare exactly one of "workflowId" or "stepId"'
+    });
+  }
+  if (handler.version != null && !handler.workflowId) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["version"],
+      message: "errorHandler.version only applies to the workflowId form"
+    });
+  }
+});
 const workflowStepSchema = z.object({
   stepId: z.string().min(1).max(100).regex(/^[a-z0-9_-]+$/, "Step ID must contain only lowercase letters, numbers, hyphens, and underscores"),
   stepName: z.string().min(1).max(255),
@@ -270,8 +454,37 @@ const workflowStepSchema = z.object({
   // ISO 8601 duration
   retryPolicy: retryPolicySchema.optional(),
   // Pre-conditions for START step (business rules to validate before workflow can be started)
-  preConditions: z.array(startPreConditionSchema).optional()
+  preConditions: z.array(startPreConditionSchema).optional(),
+  // What happens when this step fails and no error route is wired (spec 5.9).
+  errorDirective: stepErrorDirectiveSchema.optional(),
+  /**
+   * The BUSINESS milestone this step announces when it completes.
+   *
+   * An annotation rather than a step type, deliberately: a milestone is not a
+   * step, and modelling it as one would make "the stage reached after the join"
+   * unexpressible without a no-op node between the join and whatever follows it.
+   * Any step can carry one — an AUTOMATED step, a PARALLEL_JOIN, a USER_TASK —
+   * and the engine emits `workflows.instance.milestone_reached` on completion.
+   *
+   * The key belongs to a vocabulary the consuming module declares; this module
+   * only bounds its shape. A key nobody declares is a warning THERE, never an
+   * error here — the engine emits what the author wrote.
+   */
+  milestone: z.string().min(1).max(100).regex(/^[a-z0-9_]+$/, "Milestone key must contain only lowercase letters, digits and underscores").optional(),
+  // Visual-editor node coordinate persisted in the jsonb definition so a saved
+  // graph re-opens exactly as the author arranged it. Additive/optional — legacy
+  // and code-authored definitions omit it and auto-arrange on load.
+  _editorPosition: z.object({ x: z.number(), y: z.number() }).optional(),
+  // Editor-owned, never executed. Holds `unmappedConfig`: config a step-type
+  // conversion could not map onto the new type (spec 4.5). The engine ignores
+  // this object entirely; it exists so a conversion never destroys authored
+  // configuration and a conversion back can recover it.
+  metadata: z.record(z.string(), z.any()).optional()
 }).superRefine((step, ctx) => {
+  if (step.stepType === "WAIT_FOR_CONDITION") {
+    refineWaitForConditionStep(step.config || {}, ctx);
+    return;
+  }
   if (step.stepType !== "WAIT_FOR_TIMER") return;
   const config = step.config || {};
   const hasDuration = config.duration != null && config.duration !== "";
@@ -328,10 +541,23 @@ const workflowTransitionSchema = z.object({
   trigger: transitionTriggerSchema,
   preConditions: z.array(transitionConditionSchema).optional(),
   postConditions: z.array(transitionConditionSchema).optional(),
+  // Inline condition in the business_rules ConditionExpression language — the
+  // one condition language platform-wide. `findValidTransitions` has always
+  // evaluated `transition.condition`; declaring it here makes author-time
+  // routing (IF_ELSE / SWITCH cases) survive a save round-trip.
+  condition: conditionExpressionSchema,
   activities: z.array(activityDefinitionSchema).optional(),
   // Activities to execute during transition
   continueOnActivityFailure: z.boolean().default(false).optional(),
   // If true, transition continues even when activities fail
+  // Error route marker (spec 5.9). Normal routing never selects an `error`
+  // route; the engine follows it only when the source step fails.
+  kind: transitionKindSchema.optional(),
+  // Which of spec 7.2's five fixed disposition kinds an `outcome` route carries.
+  // Additive and optional: a definition declaring no outcome routes never
+  // carries it, and an unknown value is surfaced as a Problems-panel issue
+  // rather than rejected, so an older definition never fails to load.
+  outcomeKind: z.string().min(1).max(50).optional(),
   priority: z.number().int().min(0).max(9999).default(0)
 });
 const workflowDefinitionTriggerSchema = z.object({
@@ -362,7 +588,7 @@ const workflowDefinitionTriggerSchema = z.object({
 function validateParallelForkJoin(definition) {
   const issues = [];
   const steps = definition.steps ?? [];
-  const transitions = definition.transitions ?? [];
+  const transitions = excludeNonNormalTransitions(definition.transitions ?? []);
   const stepById = /* @__PURE__ */ new Map();
   for (const step of steps) stepById.set(step.stepId, step);
   const outgoingByStep = /* @__PURE__ */ new Map();
@@ -485,11 +711,31 @@ function validateParallelForkJoin(definition) {
   }
   return issues;
 }
+const contextSchemaFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.enum(["text", "number", "boolean", "select", "date"]),
+  label: z.string().optional(),
+  required: z.boolean().optional(),
+  options: z.array(z.string()).optional()
+});
+const contextSchemaSchema = z.object({
+  input: z.object({
+    fields: z.array(contextSchemaFieldSchema)
+  }).optional()
+});
 const workflowDefinitionDataSchema = z.object({
   steps: z.array(workflowStepSchema).min(2, "Workflow must have at least START and END steps"),
   transitions: z.array(workflowTransitionSchema).min(1, "Workflow must have at least one transition"),
   triggers: z.array(workflowDefinitionTriggerSchema).optional(),
   // Event triggers for automatic workflow start
+  contextSchema: contextSchemaSchema.optional(),
+  // Declared typed-input contract (spec §3.1) — canonical input contract
+  io: workflowIoContractSchema.optional(),
+  // Sub-workflow input/output port contract; io.input is a read-through alias of contextSchema.input for the ledger
+  interpolation: z.enum(["strict", "lenient"]).optional(),
+  // Interpolation mode (spec §3.6): absent = lenient; the POST create route defaults NEW definitions to 'strict' — never default here, it would flip existing lenient definitions on their next full-body update
+  errorHandler: workflowErrorHandlerSchema.optional(),
+  // Catch-all error handler (spec §5.9)
   queries: z.array(z.any()).optional(),
   // For Phase 7
   signals: z.array(z.any()).optional(),
@@ -504,17 +750,113 @@ const workflowDefinitionDataSchema = z.object({
       message: `[${issue.code}] ${issue.message}`
     });
   }
+  definition.steps.forEach((step, index) => {
+    if (step.stepType !== "WAIT_FOR_CONDITION") return;
+    const hasOutgoing = definition.transitions.some(
+      (transition) => transition.fromStepId === step.stepId
+    );
+    if (hasOutgoing) return;
+    ctx.addIssue({
+      code: "custom",
+      path: ["steps", index],
+      message: `WAIT_FOR_CONDITION step "${step.stepId}" requires at least one outgoing transition`
+    });
+  });
+});
+const sampleEnvelopeSchema = z.object({
+  pinnedAt: z.string().datetime({ offset: true }),
+  source: z.enum(["manual", "test"]),
+  data: z.unknown()
+});
+const WORKFLOW_EDITOR_SAMPLES_MAX_CHARS = 65536;
+const WORKFLOW_EDITOR_ANNOTATIONS_MAX_CHARS = 65536;
+const startFixtureSchema = z.object({
+  name: z.string().min(1).max(WORKFLOW_START_FIXTURE_NAME_MAX),
+  savedAt: z.string().datetime({ offset: true }),
+  context: z.record(z.string(), z.any())
+});
+const annotationPointSchema = z.object({ x: z.number(), y: z.number() });
+const annotationSizeSchema = z.object({ width: z.number().positive(), height: z.number().positive() });
+const editorNoteSchema = z.object({
+  id: z.string().min(1).max(100),
+  markdown: z.string().max(1e4),
+  position: annotationPointSchema,
+  size: annotationSizeSchema
+});
+const editorGroupSchema = z.object({
+  id: z.string().min(1).max(100),
+  name: z.string().max(200),
+  rect: z.object({ x: z.number(), y: z.number(), width: z.number().positive(), height: z.number().positive() }),
+  collapsed: z.boolean().optional()
+});
+const editorAnnotationsSchema = z.object({
+  notes: z.array(editorNoteSchema).optional(),
+  groups: z.array(editorGroupSchema).optional()
 });
 const workflowMetadataSchema = z.object({
   tags: z.array(z.string().max(50)).optional(),
   category: z.string().max(100).optional(),
-  icon: z.string().max(100).optional()
+  icon: z.string().max(100).optional(),
+  // Forward-compatibility guard (spec section 5.8): engines below this version
+  // refuse to instantiate the definition instead of misexecuting it.
+  minEngineVersion: z.number().int().min(1).optional(),
+  editor: z.object({
+    samples: z.record(z.string(), sampleEnvelopeSchema).optional(),
+    annotations: editorAnnotationsSchema.optional(),
+    // Named START contexts (spec section 8.1). A different thing from a pinned
+    // per-step sample, which is why it gets its own key and its own cap.
+    fixtures: z.record(z.string(), startFixtureSchema).optional()
+  }).passthrough().optional()
+}).superRefine((metadata, ctx) => {
+  const samples = metadata.editor?.samples;
+  if (samples && JSON.stringify(samples).length > WORKFLOW_EDITOR_SAMPLES_MAX_CHARS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["editor", "samples"],
+      message: `Pinned samples exceed the ${WORKFLOW_EDITOR_SAMPLES_MAX_CHARS}-character limit; unpin or shrink samples before saving`
+    });
+  }
+  const annotations = metadata.editor?.annotations;
+  if (annotations && JSON.stringify(annotations).length > WORKFLOW_EDITOR_ANNOTATIONS_MAX_CHARS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["editor", "annotations"],
+      message: `Notes and groups exceed the ${WORKFLOW_EDITOR_ANNOTATIONS_MAX_CHARS}-character limit; shorten or remove some before saving`
+    });
+  }
+  const fixtures = metadata.editor?.fixtures;
+  if (fixtures && JSON.stringify(fixtures).length > WORKFLOW_START_FIXTURES_MAX_CHARS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["editor", "fixtures"],
+      message: `Start fixtures exceed the ${WORKFLOW_START_FIXTURES_MAX_CHARS}-character limit; delete or shrink fixtures before saving`
+    });
+  }
+  if (fixtures && Object.keys(fixtures).length > WORKFLOW_START_FIXTURES_MAX_COUNT) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["editor", "fixtures"],
+      message: `A definition may keep at most ${WORKFLOW_START_FIXTURES_MAX_COUNT} start fixtures`
+    });
+  }
 });
 const dateOrNull = z.preprocess((value) => {
   if (value === void 0 || value === null || value === "") return null;
   const date = value instanceof Date ? value : new Date(String(value));
   return Number.isNaN(date.getTime()) ? null : date;
 }, z.date().nullable());
+const workflowKindSchema = z.enum(["workflow", "component"]);
+const workflowLifecycleSchema = z.enum(["draft", "published", "archived"]);
+const componentHasNoTriggers = (data, ctx) => {
+  const triggers = data.definition && data.definition.triggers;
+  if (data.kind === "component" && Array.isArray(triggers) && triggers.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["definition", "triggers"],
+      message: "A component workflow cannot declare event triggers"
+    });
+  }
+};
 const createWorkflowDefinitionSchema = z.object({
   workflowId: z.string().min(1).max(100).regex(/^[a-z0-9._-]+$/, "Workflow ID must contain only lowercase letters, numbers, dots, hyphens, and underscores"),
   workflowName: z.string().min(1).max(255),
@@ -523,12 +865,15 @@ const createWorkflowDefinitionSchema = z.object({
   definition: workflowDefinitionDataSchema,
   metadata: workflowMetadataSchema.optional().nullable(),
   enabled: z.boolean().default(true),
+  kind: workflowKindSchema.default("workflow"),
+  lifecycle: workflowLifecycleSchema.default("published"),
   effectiveFrom: dateOrNull.optional(),
   effectiveTo: dateOrNull.optional(),
   tenantId: uuid,
   organizationId: uuid,
   createdBy: z.string().max(255).optional().nullable()
 });
+const workflowGrantedFeaturesSchema = z.array(z.string().min(1).max(255)).max(200).optional().nullable();
 const createWorkflowDefinitionInputSchema = z.object({
   workflowId: z.string().min(1).max(100).regex(/^[a-z0-9._-]+$/, "Workflow ID must contain only lowercase letters, numbers, dots, hyphens, and underscores"),
   workflowName: z.string().min(1).max(255),
@@ -536,8 +881,12 @@ const createWorkflowDefinitionInputSchema = z.object({
   version: z.number().int().positive().default(1),
   definition: workflowDefinitionDataSchema,
   metadata: workflowMetadataSchema.optional().nullable(),
-  enabled: z.boolean().default(true).optional()
+  enabled: z.boolean().default(true).optional(),
+  kind: workflowKindSchema.optional(),
+  lifecycle: workflowLifecycleSchema.optional(),
+  grantedFeatures: workflowGrantedFeaturesSchema
 });
+const createWorkflowDefinitionInputCheckedSchema = createWorkflowDefinitionInputSchema.superRefine(componentHasNoTriggers);
 const updateWorkflowDefinitionSchema = createWorkflowDefinitionSchema.partial().extend({
   id: uuid
 });
@@ -549,9 +898,13 @@ const updateWorkflowDefinitionInputSchema = z.object({
   definition: workflowDefinitionDataSchema.optional(),
   metadata: workflowMetadataSchema.optional().nullable(),
   enabled: z.boolean().optional(),
+  kind: workflowKindSchema.optional(),
+  lifecycle: workflowLifecycleSchema.optional(),
   effectiveFrom: dateOrNull.optional(),
-  effectiveTo: dateOrNull.optional()
+  effectiveTo: dateOrNull.optional(),
+  grantedFeatures: workflowGrantedFeaturesSchema
 }).strict();
+const updateWorkflowDefinitionInputCheckedSchema = updateWorkflowDefinitionInputSchema.superRefine(componentHasNoTriggers);
 const workflowDefinitionFilterSchema = z.object({
   workflowId: z.string().optional(),
   workflowName: z.string().optional(),
@@ -559,6 +912,21 @@ const workflowDefinitionFilterSchema = z.object({
   tenantId: uuid.optional(),
   organizationId: uuid.optional()
 });
+const workflowDefinitionDraftDataSchema = z.object({
+  steps: z.array(z.record(z.string(), z.unknown())),
+  transitions: z.array(z.record(z.string(), z.unknown()))
+}).passthrough();
+const upsertWorkflowDefinitionDraftInputSchema = z.object({
+  definition: workflowDefinitionDraftDataSchema,
+  metadata: workflowMetadataSchema.optional().nullable(),
+  baseUpdatedAt: dateOrNull.optional()
+}).strict();
+const testWorkflowStepInputSchema = z.object({
+  stepId: z.string().min(1).optional(),
+  activityType: z.string().min(1),
+  config: z.record(z.string(), z.unknown()),
+  context: z.record(z.string(), z.unknown()).default({})
+}).strict();
 const workflowInstanceMetadataSchema = z.object({
   entityType: z.string().max(100).optional(),
   entityId: z.string().max(255).optional(),
@@ -581,6 +949,7 @@ const createWorkflowInstanceSchema = z.object({
   errorMessage: z.string().max(5e3).optional().nullable(),
   errorDetails: z.any().optional().nullable(),
   retryCount: z.number().int().min(0).default(0),
+  isDryRun: z.boolean().default(false),
   tenantId: uuid,
   organizationId: uuid
 });
@@ -593,6 +962,7 @@ const workflowInstanceFilterSchema = z.object({
   status: workflowInstanceStatusSchema.optional(),
   correlationKey: z.string().optional(),
   currentStepId: z.string().optional(),
+  isDryRun: z.boolean().optional(),
   tenantId: uuid.optional(),
   organizationId: uuid.optional()
 });
@@ -646,6 +1016,24 @@ const createUserTaskSchema = z.object({
 const updateUserTaskSchema = createUserTaskSchema.partial().extend({
   id: uuid
 });
+const reassignUserTaskSchema = z.object({
+  assignedTo: z.string().max(255).nullable().optional().transform((value) => {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    return trimmed.length > 0 ? trimmed : null;
+  }),
+  assignedToRoles: z.array(z.string().max(100)).nullable().optional().transform((value) => {
+    if (!Array.isArray(value)) return null;
+    const roles = value.map((role) => role.trim()).filter((role) => role.length > 0);
+    return roles.length > 0 ? roles : null;
+  }),
+  reason: z.string().max(2e3).nullable().optional().transform((value) => {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    return trimmed.length > 0 ? trimmed : null;
+  })
+}).refine((value) => value.assignedTo !== null || value.assignedToRoles !== null, {
+  message: "Provide an assignee or at least one role queue",
+  path: ["assignedTo"]
+});
 const userTaskFilterSchema = z.object({
   workflowInstanceId: uuid.optional(),
   status: userTaskStatusSchema.optional(),
@@ -688,7 +1076,19 @@ const startWorkflowInputSchema = z.object({
   version: z.number().int().positive().optional(),
   correlationKey: z.string().optional(),
   initialContext: z.record(z.string(), z.any()).optional(),
-  metadata: workflowInstanceMetadataSchema.optional()
+  metadata: workflowInstanceMetadataSchema.optional(),
+  /**
+   * Start the run as a side-effect-free simulation (spec section 8.2). Opting
+   * IN is the only way to get one: absent means a real run, exactly as before.
+   * The route gates it behind `workflows.definitions.test_run`.
+   */
+  dryRun: z.boolean().optional(),
+  /**
+   * Pause before each step so the author can inspect the context and continue
+   * or abort (spec section 8.2). Gated by the same `test_run` feature as
+   * `dryRun`, and independent of it: a real run can be stepped through too.
+   */
+  stepThrough: z.boolean().optional()
 });
 const triggerFilterOperatorSchema = z.enum([
   "eq",
@@ -768,60 +1168,103 @@ const eventTriggerFilterSchema = z.object({
   organizationId: uuid.optional()
 });
 export {
+  CONDITION_POLL_INTERVAL_MAX_MS,
+  CONDITION_POLL_INTERVAL_MIN_MS,
+  WORKFLOW_EDITOR_ANNOTATIONS_MAX_CHARS,
+  WORKFLOW_EDITOR_SAMPLES_MAX_CHARS,
   activityDefinitionSchema,
   activityRetryPolicySchema,
   activityTypeSchema,
   callApiConfigSchema,
   callWebhookConfigSchema,
+  contextSchemaFieldSchema,
+  contextSchemaSchema,
   createEventTriggerInputSchema,
   createEventTriggerSchema,
   createStepInstanceSchema,
   createUserTaskSchema,
+  createWorkflowDefinitionInputCheckedSchema,
   createWorkflowDefinitionInputSchema,
   createWorkflowDefinitionSchema,
   createWorkflowEventSchema,
   createWorkflowInstanceSchema,
+  editorAnnotationsSchema,
+  editorGroupSchema,
+  editorNoteSchema,
+  emitEventConfigSchema,
   escalationActionSchema,
   escalationTriggerSchema,
   eventPatternSchema,
   eventTriggerConfigSchema,
   eventTriggerFilterSchema,
-  isFutureIsoDateString,
-  isValidDurationString,
-  isValidIsoDateString,
+  executeFunctionConfigSchema,
+  invokeAgentConfigSchema2 as invokeAgentConfigSchema,
+  isFutureIsoDateString2 as isFutureIsoDateString,
+  isValidDurationString2 as isValidDurationString,
+  isValidIsoDateString2 as isValidIsoDateString,
   localizedMessageSchema,
+  portFieldSchema,
+  portFieldTypeSchema,
+  reassignUserTaskSchema,
   retryPolicySchema,
+  sampleEnvelopeSchema,
+  sendEmailConfigSchema,
+  setVariableAssignmentSchema,
+  setVariableConfigSchema,
+  startFixtureSchema,
   startPreConditionSchema,
   startWorkflowInputSchema,
+  stepErrorDirectiveSchema,
   stepInstanceFilterSchema,
   stepInstanceStatusSchema,
   subWorkflowConfigSchema,
+  taskDeadlineSchema2 as taskDeadlineSchema,
+  taskDecisionSchema,
+  taskEntityBindingSchema,
+  taskLocalizedStringSchema,
+  taskOnBreachSchema,
+  taskPrioritySchema2 as taskPrioritySchema,
+  taskReminderSchema2 as taskReminderSchema,
+  testWorkflowStepInputSchema,
   transitionConditionSchema,
+  transitionKindSchema,
   transitionTriggerSchema,
   triggerContextMappingSchema,
   triggerFilterConditionSchema,
   triggerFilterOperatorSchema,
+  updateEntityConfigSchema,
   updateEventTriggerInputSchema,
   updateEventTriggerSchema,
   updateStepInstanceSchema,
   updateUserTaskSchema,
+  updateWorkflowDefinitionInputCheckedSchema,
   updateWorkflowDefinitionInputSchema,
   updateWorkflowDefinitionSchema,
   updateWorkflowInstanceSchema,
+  upsertWorkflowDefinitionDraftInputSchema,
+  userTaskAssigneeKindSchema,
   userTaskConfigSchema,
   userTaskFilterSchema,
   userTaskStatusSchema,
   validateParallelForkJoin,
+  waitConfigSchema,
   workflowBranchInstanceStatusSchema,
   workflowDefinitionDataSchema,
+  workflowDefinitionDraftDataSchema,
   workflowDefinitionFilterSchema,
   workflowDefinitionTriggerSchema,
+  workflowErrorHandlerSchema,
   workflowEventFilterSchema,
   workflowExecutionContextSchema,
+  workflowGrantedFeaturesSchema,
   workflowInstanceFilterSchema,
   workflowInstanceMetadataSchema,
   workflowInstanceStatusSchema,
+  workflowIoContractSchema,
+  workflowKindSchema,
+  workflowLifecycleSchema,
   workflowMetadataSchema,
+  workflowRunOutcomeSchema,
   workflowStepSchema,
   workflowStepTypeSchema,
   workflowTransitionSchema