create-safest-tools 0.2.0

package/template/src/workflow-platform-validation.ts

@@ -0,0 +1,540 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type {
+  JsonObject,
+  JsonValue,
+  WorkflowAuthorityMode,
+  WorkflowCapabilityManifest,
+  WorkflowDefinitionInput,
+  WorkflowDependencyReference,
+  WorkflowEdgeV1,
+  WorkflowGraphV1,
+  WorkflowNodeKind,
+  WorkflowNodeV1,
+  WorkflowPublishInput,
+  WorkflowValidationIssue,
+  WorkflowValidationResult,
+} from "./workflow-platform-types";
+
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/u;
+const keyPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const versionReferencePattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u;
+const eventTypePattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$/u;
+const prohibitedExpressionPattern = /(?:__proto__|prototype|constructor|\beval\b|\bFunction\b|javascript:|\bfetch\b|\bimport\s*\(|\brequire\s*\()/u;
+const nodeKinds = new Set<WorkflowNodeKind>([
+  "start", "enrichment", "parallel_group", "join", "condition", "ai_proposal",
+  "human_task", "send_message", "wait_for_event", "delay", "delay_until",
+  "decision", "action", "handoff", "start_linked_workflow", "end",
+]);
+const purposes = new Set(["report", "appeal", "quality", "operations"] as const);
+const authorityModes = new Set<WorkflowAuthorityMode>(["off", "shadow", "assist", "bounded_auto"]);
+const dangerousKeys = new Set(["__proto__", "prototype", "constructor"]);
+
+function object(value: unknown, path: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ApiError(400, "invalid_workflow", `${path} must be an object.`, { path });
+  }
+  return value as Record<string, unknown>;
+}
+
+function knownFields(value: Record<string, unknown>, allowed: readonly string[], path: string): void {
+  const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unexpected) throw new ApiError(400, "invalid_workflow", `${path} contains unsupported field ${unexpected}.`, { path: `${path}.${unexpected}` });
+}
+
+function text(value: unknown, path: string, minimum: number, maximum: number): string {
+  if (typeof value !== "string" || value.trim().length < minimum || value.trim().length > maximum) {
+    throw new ApiError(400, "invalid_workflow", `${path} must contain ${minimum} to ${maximum} characters.`, { path });
+  }
+  if (/[\u0000-\u001f\u007f]/u.test(value)) throw new ApiError(400, "invalid_workflow", `${path} contains control characters.`, { path });
+  return value.trim();
+}
+
+function identifier(value: unknown, path: string): string {
+  const result = text(value, path, 1, 100);
+  if (!identifierPattern.test(result)) throw new ApiError(400, "invalid_workflow", `${path} must use letters, digits, underscore, or hyphen.`, { path });
+  return result;
+}
+
+function optionalText(value: unknown, path: string, maximum: number): string | undefined {
+  if (value === undefined) return undefined;
+  return text(value, path, 1, maximum);
+}
+
+function jsonValue(value: unknown, path: string, depth = 0): JsonValue {
+  if (depth > 20) throw new ApiError(400, "invalid_workflow", `${path} is nested too deeply.`, { path });
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) {
+    if (value.length > 500) throw new ApiError(400, "invalid_workflow", `${path} contains too many values.`, { path });
+    return value.map((child, index) => jsonValue(child, `${path}[${index}]`, depth + 1));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length > 500) throw new ApiError(400, "invalid_workflow", `${path} contains too many properties.`, { path });
+    const output: JsonObject = {};
+    for (const [key, child] of entries) {
+      if (dangerousKeys.has(key)) throw new ApiError(400, "invalid_workflow", `${path} contains a prohibited property.`, { path: `${path}.${key}` });
+      if (key.length < 1 || key.length > 200) throw new ApiError(400, "invalid_workflow", `${path} contains an invalid property name.`, { path });
+      output[key] = jsonValue(child, `${path}.${key}`, depth + 1);
+    }
+    return output;
+  }
+  throw new ApiError(400, "invalid_workflow", `${path} must be JSON data.`, { path });
+}
+
+function jsonObject(value: unknown, path: string): JsonObject {
+  const parsed = jsonValue(value, path);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ApiError(400, "invalid_workflow", `${path} must be an object.`, { path });
+  }
+  return parsed;
+}
+
+function parseMapping(value: unknown, path: string): Record<string, JsonValue> {
+  const parsed = jsonObject(value ?? {}, path);
+  for (const [key, expression] of Object.entries(parsed)) {
+    if (!identifierPattern.test(key)) throw new ApiError(400, "invalid_workflow", `${path}.${key} has an invalid mapped field name.`, { path: `${path}.${key}` });
+    if (typeof expression === "string" && prohibitedExpressionPattern.test(expression)) {
+      throw new ApiError(400, "unsafe_workflow_expression", `${path}.${key} contains a prohibited expression.`, { path: `${path}.${key}` });
+    }
+  }
+  return parsed;
+}
+
+function parseNode(value: unknown, index: number): WorkflowNodeV1 {
+  const path = `nodes[${index}]`;
+  const input = object(value, path);
+  knownFields(input, [
+    "id", "kind", "name", "description", "input_mapping", "timeout_policy",
+    "retry_policy", "error_port", "config", "metadata",
+  ], path);
+  if (typeof input.kind !== "string" || !nodeKinds.has(input.kind as WorkflowNodeKind)) {
+    throw new ApiError(400, "invalid_workflow", `${path}.kind is unsupported.`, { path: `${path}.kind` });
+  }
+  const metadata = input.metadata === undefined ? undefined : object(input.metadata, `${path}.metadata`);
+  if (metadata) knownFields(metadata, ["x", "y", "group_id"], `${path}.metadata`);
+  const numberOrUndefined = (candidate: unknown, childPath: string): number | undefined => {
+    if (candidate === undefined) return undefined;
+    if (typeof candidate !== "number" || !Number.isFinite(candidate) || Math.abs(candidate) > 1_000_000) {
+      throw new ApiError(400, "invalid_workflow", `${childPath} must be a bounded number.`, { path: childPath });
+    }
+    return candidate;
+  };
+  const groupId = metadata?.group_id === undefined ? undefined : identifier(metadata.group_id, `${path}.metadata.group_id`);
+  return {
+    id: identifier(input.id, `${path}.id`),
+    kind: input.kind as WorkflowNodeKind,
+    name: text(input.name, `${path}.name`, 1, 160),
+    ...(input.description === undefined ? {} : { description: text(input.description, `${path}.description`, 1, 2_000) }),
+    inputMapping: parseMapping(input.input_mapping, `${path}.input_mapping`),
+    ...(input.timeout_policy === undefined ? {} : { timeoutPolicy: jsonObject(input.timeout_policy, `${path}.timeout_policy`) }),
+    ...(input.retry_policy === undefined ? {} : { retryPolicy: jsonObject(input.retry_policy, `${path}.retry_policy`) }),
+    ...(input.error_port === undefined ? {} : { errorPort: identifier(input.error_port, `${path}.error_port`) }),
+    config: jsonObject(input.config ?? {}, `${path}.config`),
+    ...(metadata ? { metadata: {
+      ...(metadata.x === undefined ? {} : { x: numberOrUndefined(metadata.x, `${path}.metadata.x`) }),
+      ...(metadata.y === undefined ? {} : { y: numberOrUndefined(metadata.y, `${path}.metadata.y`) }),
+      ...(groupId === undefined ? {} : { groupId }),
+    } } : {}),
+  };
+}
+
+function parseEndpoint(value: unknown, path: string): { nodeId: string; port: string } {
+  const input = object(value, path);
+  knownFields(input, ["node_id", "port"], path);
+  return { nodeId: identifier(input.node_id, `${path}.node_id`), port: identifier(input.port, `${path}.port`) };
+}
+
+function parseEdge(value: unknown, index: number): WorkflowEdgeV1 {
+  const path = `edges[${index}]`;
+  const input = object(value, path);
+  knownFields(input, ["id", "from", "to", "label"], path);
+  return {
+    id: identifier(input.id, `${path}.id`),
+    from: parseEndpoint(input.from, `${path}.from`),
+    to: parseEndpoint(input.to, `${path}.to`),
+    ...(input.label === undefined ? {} : { label: optionalText(input.label, `${path}.label`, 160) }),
+  };
+}
+
+export function parseWorkflowGraph(value: unknown): WorkflowGraphV1 {
+  const input = object(value, "workflow");
+  knownFields(input, [
+    "schema_version", "purpose", "entry_node_id", "nodes", "edges", "input_schema",
+    "terminal_codes", "default_policies",
+  ], "workflow");
+  if (input.schema_version !== "1") throw new ApiError(400, "unsupported_workflow_schema", "workflow.schema_version must be 1.", { path: "workflow.schema_version" });
+  if (typeof input.purpose !== "string" || !purposes.has(input.purpose as WorkflowGraphV1["purpose"])) {
+    throw new ApiError(400, "invalid_workflow", "workflow.purpose is unsupported.", { path: "workflow.purpose" });
+  }
+  if (!Array.isArray(input.nodes) || input.nodes.length < 2 || input.nodes.length > 200) {
+    throw new ApiError(400, "invalid_workflow", "workflow.nodes must contain 2 to 200 nodes.", { path: "workflow.nodes" });
+  }
+  if (!Array.isArray(input.edges) || input.edges.length < 1 || input.edges.length > 1_000) {
+    throw new ApiError(400, "invalid_workflow", "workflow.edges must contain 1 to 1,000 edges.", { path: "workflow.edges" });
+  }
+  if (!Array.isArray(input.terminal_codes) || input.terminal_codes.length < 1 || input.terminal_codes.length > 100) {
+    throw new ApiError(400, "invalid_workflow", "workflow.terminal_codes must contain 1 to 100 codes.", { path: "workflow.terminal_codes" });
+  }
+  const terminalCodes = input.terminal_codes.map((value, index) => identifier(value, `workflow.terminal_codes[${index}]`));
+  if (new Set(terminalCodes).size !== terminalCodes.length) throw new ApiError(400, "invalid_workflow", "workflow.terminal_codes contains duplicates.");
+  const defaults = object(input.default_policies ?? {}, "workflow.default_policies");
+  knownFields(defaults, ["timeout", "retry", "data_retention_class"], "workflow.default_policies");
+  return {
+    schemaVersion: "1",
+    purpose: input.purpose as WorkflowGraphV1["purpose"],
+    entryNodeId: identifier(input.entry_node_id, "workflow.entry_node_id"),
+    nodes: input.nodes.map(parseNode),
+    edges: input.edges.map(parseEdge),
+    inputSchema: jsonObject(input.input_schema ?? { type: "object" }, "workflow.input_schema"),
+    terminalCodes,
+    defaultPolicies: {
+      ...(defaults.timeout === undefined ? {} : { timeout: jsonValue(defaults.timeout, "workflow.default_policies.timeout") }),
+      ...(defaults.retry === undefined ? {} : { retry: jsonObject(defaults.retry, "workflow.default_policies.retry") }),
+      ...(defaults.data_retention_class === undefined ? {} : {
+        dataRetentionClass: identifier(defaults.data_retention_class, "workflow.default_policies.data_retention_class"),
+      }),
+    },
+  };
+}
+
+function configString(node: WorkflowNodeV1, key: string): string | null {
+  const value = node.config[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function configStringList(node: WorkflowNodeV1, key: string): string[] {
+  const value = node.config[key];
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function issue(code: string, message: string, nodeId?: string, edgeId?: string): WorkflowValidationIssue {
+  return { code, message, ...(nodeId ? { nodeId } : {}), ...(edgeId ? { edgeId } : {}) };
+}
+
+function dependencyReferences(nodes: WorkflowNodeV1[]): WorkflowDependencyReference[] {
+  const references = new Map<string, WorkflowDependencyReference>();
+  const add = (type: WorkflowDependencyReference["type"], versionId: string | null, nodeId: string) => {
+    if (!versionId || !versionReferencePattern.test(versionId)) return;
+    const dependency = { type, key: `${type}:${nodeId}`, versionId };
+    references.set(`${type}:${versionId}`, dependency);
+  };
+  for (const node of nodes) {
+    add("component", configString(node, "component_version_id"), node.id);
+    add("connection", configString(node, "connection_version_id"), node.id);
+    add("policy", configString(node, "policy_version_id"), node.id);
+    add("template", configString(node, "template_version_id"), node.id);
+    add("model_alias", configString(node, "model_alias_version_id"), node.id);
+    add("agent", configString(node, "agent_version_id"), node.id);
+    add("workflow", configString(node, "workflow_version_id"), node.id);
+  }
+  return [...references.values()].sort((left, right) => `${left.type}:${left.versionId}`.localeCompare(`${right.type}:${right.versionId}`));
+}
+
+function capabilityManifest(graph: WorkflowGraphV1, estimatedMaximumSteps: number): WorkflowCapabilityManifest {
+  const capabilities = new Set<string>();
+  const components = new Set<string>();
+  const connections = new Set<string>();
+  const eventTypes = new Set<string>();
+  const audiences = new Set<string>();
+  const actionCodes = new Set<string>();
+  let maximumParallelBranches = 1;
+  for (const node of graph.nodes) {
+    const capabilityByKind: Partial<Record<WorkflowNodeKind, string>> = {
+      enrichment: "component.execute", ai_proposal: "agent.execute", human_task: "task.create",
+      send_message: "message.send", wait_for_event: "event.wait", decision: "decision.record",
+      action: "action.propose", handoff: "queue.handoff", start_linked_workflow: "workflow.linked.start",
+    };
+    const capability = capabilityByKind[node.kind];
+    if (capability) capabilities.add(capability);
+    const component = configString(node, "component_version_id");
+    const connection = configString(node, "connection_version_id");
+    const eventType = configString(node, "event_type");
+    const audience = configString(node, "audience");
+    const actionCode = configString(node, "action_code");
+    if (component) components.add(component);
+    if (connection) connections.add(connection);
+    if (eventType) eventTypes.add(eventType);
+    if (audience) audiences.add(audience);
+    if (actionCode) actionCodes.add(actionCode);
+    if (node.kind === "parallel_group") maximumParallelBranches = Math.max(maximumParallelBranches, configStringList(node, "branch_ports").length);
+  }
+  return {
+    version: 1,
+    capabilities: [...capabilities].sort(),
+    components: [...components].sort(),
+    connections: [...connections].sort(),
+    eventTypes: [...eventTypes].sort(),
+    audiences: [...audiences].sort(),
+    actionCodes: [...actionCodes].sort(),
+    maximumParallelBranches,
+    maximumStepExecutions: estimatedMaximumSteps,
+  };
+}
+
+export function validateWorkflowGraph(graph: WorkflowGraphV1, authorityMode: WorkflowAuthorityMode = "assist"): WorkflowValidationResult {
+  const errors: WorkflowValidationIssue[] = [];
+  const warnings: WorkflowValidationIssue[] = [];
+  const nodeById = new Map<string, WorkflowNodeV1>();
+  const edgeIds = new Set<string>();
+  const outgoing = new Map<string, WorkflowEdgeV1[]>();
+  const incoming = new Map<string, WorkflowEdgeV1[]>();
+  for (const node of graph.nodes) {
+    if (nodeById.has(node.id)) errors.push(issue("duplicate_node_id", `Node ID ${node.id} is duplicated.`, node.id));
+    else nodeById.set(node.id, node);
+    outgoing.set(node.id, []);
+    incoming.set(node.id, []);
+  }
+  for (const edge of graph.edges) {
+    if (edgeIds.has(edge.id)) errors.push(issue("duplicate_edge_id", `Edge ID ${edge.id} is duplicated.`, undefined, edge.id));
+    edgeIds.add(edge.id);
+    if (!nodeById.has(edge.from.nodeId) || !nodeById.has(edge.to.nodeId)) {
+      errors.push(issue("dangling_edge", `Edge ${edge.id} references a missing node.`, undefined, edge.id));
+      continue;
+    }
+    if (edge.from.nodeId === edge.to.nodeId) errors.push(issue("self_cycle", `Edge ${edge.id} creates a self-cycle.`, edge.from.nodeId, edge.id));
+    outgoing.get(edge.from.nodeId)!.push(edge);
+    incoming.get(edge.to.nodeId)!.push(edge);
+  }
+  const startNodes = graph.nodes.filter((node) => node.kind === "start");
+  const endNodes = graph.nodes.filter((node) => node.kind === "end");
+  if (startNodes.length !== 1) errors.push(issue("unique_start_required", "A workflow must contain exactly one start node."));
+  if (startNodes[0]?.id !== graph.entryNodeId) errors.push(issue("entry_must_be_start", "entry_node_id must reference the unique start node.", graph.entryNodeId));
+  if (!endNodes.length) errors.push(issue("terminal_required", "A workflow must contain at least one end node."));
+  if (startNodes[0] && (incoming.get(startNodes[0].id)?.length ?? 0) > 0) errors.push(issue("start_has_incoming_edge", "The start node cannot have incoming edges.", startNodes[0].id));
+  for (const node of endNodes) {
+    if ((outgoing.get(node.id)?.length ?? 0) > 0) errors.push(issue("end_has_outgoing_edge", "An end node cannot have outgoing edges.", node.id));
+    const terminalCode = configString(node, "terminal_code");
+    if (!terminalCode || !graph.terminalCodes.includes(terminalCode)) errors.push(issue("invalid_terminal_code", "An end node must reference a declared terminal code.", node.id));
+  }
+  for (const [nodeId, edges] of outgoing) {
+    const ports = new Set<string>();
+    for (const edge of edges) {
+      if (ports.has(edge.from.port)) errors.push(issue("ambiguous_port", `Node ${nodeId} has multiple edges from port ${edge.from.port}.`, nodeId, edge.id));
+      ports.add(edge.from.port);
+    }
+  }
+
+  const color = new Map<string, 0 | 1 | 2>();
+  const topologicalOrder: string[] = [];
+  const visit = (nodeId: string) => {
+    const state = color.get(nodeId) ?? 0;
+    if (state === 1) {
+      errors.push(issue("cycle_detected", `A directed cycle includes node ${nodeId}.`, nodeId));
+      return;
+    }
+    if (state === 2) return;
+    color.set(nodeId, 1);
+    for (const edge of outgoing.get(nodeId) ?? []) visit(edge.to.nodeId);
+    color.set(nodeId, 2);
+    topologicalOrder.push(nodeId);
+  };
+  if (nodeById.has(graph.entryNodeId)) visit(graph.entryNodeId);
+  const reachableNodeIds = [...color.entries()].filter(([, state]) => state === 2).map(([nodeId]) => nodeId).sort();
+  for (const node of graph.nodes) {
+    if (!color.has(node.id)) errors.push(issue("unreachable_node", `Node ${node.id} is unreachable from the start node.`, node.id));
+    if (node.kind !== "start" && (incoming.get(node.id)?.length ?? 0) === 0) errors.push(issue("missing_incoming_edge", `Node ${node.id} has no incoming edge.`, node.id));
+    if (node.kind !== "end" && (outgoing.get(node.id)?.length ?? 0) === 0) errors.push(issue("missing_outgoing_edge", `Node ${node.id} has no outgoing edge.`, node.id));
+  }
+
+  for (const node of graph.nodes) {
+    const ports = new Set((outgoing.get(node.id) ?? []).map((edge) => edge.from.port));
+    const requirePort = (port: string, code = "required_port_missing") => {
+      if (!ports.has(port)) errors.push(issue(code, `Node ${node.id} requires an outgoing ${port} port.`, node.id));
+    };
+    if (node.kind === "enrichment") {
+      if (!configString(node, "component_version_id")) errors.push(issue("component_version_required", "An enrichment node must pin a component version.", node.id));
+      requirePort("success");
+      requirePort(node.errorPort ?? "error");
+    }
+    if (node.kind === "parallel_group") {
+      const branchPorts = configStringList(node, "branch_ports");
+      const joinNodeId = configString(node, "join_node_id");
+      if (branchPorts.length < 2 || branchPorts.length > 32 || new Set(branchPorts).size !== branchPorts.length) {
+        errors.push(issue("invalid_parallel_branches", "A parallel group must declare 2 to 32 unique branch_ports.", node.id));
+      }
+      for (const port of branchPorts) requirePort(port, "parallel_branch_port_missing");
+      if (!joinNodeId || nodeById.get(joinNodeId)?.kind !== "join") errors.push(issue("parallel_join_required", "A parallel group must reference a matching join node.", node.id));
+    }
+    if (node.kind === "join") {
+      const requiredBranches = configStringList(node, "required_branches");
+      if (!requiredBranches.length) errors.push(issue("join_required_branch_missing", "A join must declare at least one required branch.", node.id));
+      requirePort("success");
+    }
+    if (node.kind === "condition") {
+      const casePorts = configStringList(node, "case_ports");
+      const defaultPort = configString(node, "default_port");
+      if (!casePorts.length) errors.push(issue("condition_cases_required", "A condition must declare case_ports.", node.id));
+      for (const port of casePorts) requirePort(port, "condition_port_missing");
+      if (!defaultPort) errors.push(issue("condition_default_required", "A condition must declare a default_port.", node.id));
+      else requirePort(defaultPort, "condition_default_port_missing");
+      const cases = node.config.cases;
+      const configuredCasePorts = Array.isArray(cases)
+        ? cases.flatMap((entry) => entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.port === "string" && "when" in entry ? [entry.port] : [])
+        : cases && typeof cases === "object" ? Object.keys(cases) : [];
+      if (configuredCasePorts.length !== casePorts.length || new Set(configuredCasePorts).size !== configuredCasePorts.length
+        || casePorts.some((port) => !configuredCasePorts.includes(port))) {
+        errors.push(issue("condition_case_expression_mismatch", "Every declared condition case port must have exactly one restricted expression.", node.id));
+      }
+      if (defaultPort && casePorts.includes(defaultPort)) errors.push(issue("condition_default_overlaps_case", "The condition default port must be distinct from its case ports.", node.id));
+    }
+    if (node.kind === "ai_proposal") {
+      if (!configString(node, "agent_version_id") && !configString(node, "component_version_id")) errors.push(issue("ai_version_required", "An AI proposal must pin an agent or component version.", node.id));
+      const resultPorts = configStringList(node, "result_ports");
+      if (!resultPorts.length) errors.push(issue("ai_result_ports_required", "An AI proposal must declare allowed result_ports.", node.id));
+      for (const port of resultPorts) requirePort(port, "ai_result_port_missing");
+      requirePort(node.errorPort ?? "error");
+    }
+    if (node.kind === "human_task") {
+      if (!configString(node, "queue_id")) errors.push(issue("human_task_queue_required", "A human task must declare an eligible queue_id.", node.id));
+      if (!node.config.response_schema || typeof node.config.response_schema !== "object") errors.push(issue("human_task_schema_required", "A human task must declare response_schema.", node.id));
+      requirePort("completed");
+      requirePort("timeout");
+    }
+    if (node.kind === "send_message") {
+      const audience = configString(node, "audience");
+      if (!audience || !["reporter", "affected_user", "internal"].includes(audience)) errors.push(issue("message_audience_required", "A message node must declare an immutable supported audience.", node.id));
+      if (!configString(node, "template_version_id")) errors.push(issue("message_template_required", "A message node must pin a template version.", node.id));
+      const deliveryChannels = Array.isArray(node.config.delivery_channels)
+        ? configStringList(node, "delivery_channels") : audience === "internal" ? [] : ["customer_webhook", "email"];
+      if ((audience !== "internal" && !deliveryChannels.length) || deliveryChannels.some((channel) => !["customer_webhook", "email"].includes(channel))
+        || new Set(deliveryChannels).size !== deliveryChannels.length) {
+        errors.push(issue("message_delivery_channels_invalid", "Message delivery_channels must be a unique subset of customer_webhook and email.", node.id));
+      }
+      if (audience === "internal" && deliveryChannels.length) {
+        errors.push(issue("internal_message_external_delivery_denied", "Internal messages cannot use external delivery channels.", node.id));
+      }
+      requirePort("sent");
+      requirePort(node.errorPort ?? "error");
+    }
+    if (node.kind === "wait_for_event") {
+      const eventType = configString(node, "event_type");
+      const timeoutSeconds = node.config.timeout_seconds;
+      if (!eventType || !eventTypePattern.test(eventType)) errors.push(issue("event_type_required", "A wait node must declare a Workflow-compatible event_type.", node.id));
+      if (!Number.isInteger(timeoutSeconds) || Number(timeoutSeconds) < 1 || Number(timeoutSeconds) > 31_536_000) errors.push(issue("wait_timeout_required", "A wait node timeout_seconds must be between 1 and 31,536,000.", node.id));
+      requirePort("received");
+      requirePort("timeout");
+    }
+    if (node.kind === "delay" || node.kind === "delay_until") {
+      if (node.kind === "delay" && (!Number.isInteger(node.config.duration_seconds) || Number(node.config.duration_seconds) < 1)) errors.push(issue("delay_duration_required", "A delay node must declare a positive duration_seconds.", node.id));
+      if (node.kind === "delay_until" && !node.inputMapping.timestamp) errors.push(issue("delay_timestamp_required", "A delay_until node must map timestamp.", node.id));
+      requirePort("completed");
+    }
+    if (node.kind === "decision") {
+      if (!configString(node, "policy_version_id")) errors.push(issue("decision_policy_required", "A decision node must pin a policy version.", node.id));
+      for (const field of ["decision_code", "policy_code", "rationale", "evidence_references", "finding_ids"]) {
+        if (!(field in node.inputMapping)) errors.push(issue("decision_mapping_required", `A decision node must map ${field}.`, node.id));
+      }
+      requirePort("recorded");
+      requirePort(node.errorPort ?? "error");
+    }
+    if (node.kind === "action") {
+      if (!configString(node, "component_version_id") || !configString(node, "action_code")) errors.push(issue("action_component_required", "An action node must pin a component version and action_code.", node.id));
+      if (!node.config.approval_policy || typeof node.config.approval_policy !== "object") errors.push(issue("action_approval_required", "An action node must declare approval_policy.", node.id));
+      if (!node.inputMapping.idempotency_key) errors.push(issue("action_idempotency_required", "An action node must map a stable idempotency_key.", node.id));
+      for (const field of ["target", "payload", "preconditions"]) {
+        if (!(field in node.inputMapping)) errors.push(issue("action_mapping_required", `An action node must map ${field}.`, node.id));
+      }
+      requirePort("applied");
+      requirePort("rejected");
+      requirePort("timeout");
+      requirePort(node.errorPort ?? "error");
+      if (authorityMode === "shadow") errors.push(issue("shadow_action_prohibited", "A shadow workflow cannot contain an executable action node.", node.id));
+    }
+    if (node.kind === "handoff") {
+      if (!configStringList(node, "allowed_queue_ids").length) errors.push(issue("handoff_allowlist_required", "A handoff must declare allowed_queue_ids.", node.id));
+      if (!node.inputMapping.queue_id) errors.push(issue("handoff_queue_mapping_required", "A handoff must map queue_id.", node.id));
+      requirePort("handed_off");
+      requirePort(node.errorPort ?? "error");
+    }
+    if (node.kind === "start_linked_workflow") {
+      if (!configString(node, "workflow_version_id")) errors.push(issue("linked_workflow_required", "A linked workflow node must pin a workflow version.", node.id));
+      requirePort("started");
+      requirePort(node.errorPort ?? "error");
+    }
+  }
+  const estimatedMaximumSteps = Math.min(1_000_000, graph.nodes.length + graph.edges.length);
+  if (estimatedMaximumSteps > 1_000) errors.push(issue("step_budget_exceeded", "The graph can exceed the 1,000-step product limit."));
+  if (graph.nodes.length > 150) warnings.push(issue("large_workflow", "This workflow is close to the 200-node publication limit."));
+  topologicalOrder.reverse();
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    dependencies: dependencyReferences(graph.nodes),
+    capabilityManifest: capabilityManifest(graph, estimatedMaximumSteps),
+    reachableNodeIds,
+    topologicalOrder,
+    estimatedMaximumSteps,
+  };
+}
+
+export function parseWorkflowDefinition(value: unknown): WorkflowDefinitionInput {
+  const input = object(value, "workflow_definition");
+  knownFields(input, ["key", "name", "description", "purpose"], "workflow_definition");
+  const key = text(input.key, "workflow_definition.key", 1, 100);
+  if (!keyPattern.test(key)) throw new ApiError(400, "invalid_workflow_key", "workflow_definition.key must be lower-case kebab-case.");
+  if (typeof input.purpose !== "string" || !purposes.has(input.purpose as WorkflowGraphV1["purpose"])) {
+    throw new ApiError(400, "invalid_workflow", "workflow_definition.purpose is unsupported.");
+  }
+  return {
+    key,
+    name: text(input.name, "workflow_definition.name", 1, 160),
+    description: typeof input.description === "string" ? input.description.trim().slice(0, 2_000) : "",
+    purpose: input.purpose as WorkflowGraphV1["purpose"],
+  };
+}
+
+export function parseWorkflowPublish(value: unknown): WorkflowPublishInput {
+  const input = object(value, "workflow_publish");
+  knownFields(input, ["expected_revision", "authority_mode", "test_evidence"], "workflow_publish");
+  if (!Number.isInteger(input.expected_revision) || Number(input.expected_revision) < 1) throw new ApiError(400, "invalid_workflow", "workflow_publish.expected_revision must be a positive integer.");
+  if (typeof input.authority_mode !== "string" || !authorityModes.has(input.authority_mode as WorkflowAuthorityMode)) throw new ApiError(400, "invalid_workflow", "workflow_publish.authority_mode is unsupported.");
+  return {
+    expectedRevision: Number(input.expected_revision),
+    authorityMode: input.authority_mode as WorkflowAuthorityMode,
+    testEvidence: jsonObject(input.test_evidence ?? {}, "workflow_publish.test_evidence"),
+  };
+}
+
+export function graphForStorage(graph: WorkflowGraphV1): Record<string, unknown> {
+  return {
+    schema_version: graph.schemaVersion,
+    purpose: graph.purpose,
+    entry_node_id: graph.entryNodeId,
+    nodes: graph.nodes.map((node) => ({
+      id: node.id,
+      kind: node.kind,
+      name: node.name,
+      ...(node.description ? { description: node.description } : {}),
+      input_mapping: node.inputMapping,
+      ...(node.timeoutPolicy ? { timeout_policy: node.timeoutPolicy } : {}),
+      ...(node.retryPolicy ? { retry_policy: node.retryPolicy } : {}),
+      ...(node.errorPort ? { error_port: node.errorPort } : {}),
+      config: node.config,
+      ...(node.metadata ? { metadata: {
+        ...(node.metadata.x === undefined ? {} : { x: node.metadata.x }),
+        ...(node.metadata.y === undefined ? {} : { y: node.metadata.y }),
+        ...(node.metadata.groupId ? { group_id: node.metadata.groupId } : {}),
+      } } : {}),
+    })),
+    edges: graph.edges.map((edge) => ({
+      id: edge.id,
+      from: { node_id: edge.from.nodeId, port: edge.from.port },
+      to: { node_id: edge.to.nodeId, port: edge.to.port },
+      ...(edge.label ? { label: edge.label } : {}),
+    })),
+    input_schema: graph.inputSchema,
+    terminal_codes: graph.terminalCodes,
+    default_policies: {
+      ...(graph.defaultPolicies.timeout === undefined ? {} : { timeout: graph.defaultPolicies.timeout }),
+      ...(graph.defaultPolicies.retry ? { retry: graph.defaultPolicies.retry } : {}),
+      ...(graph.defaultPolicies.dataRetentionClass ? { data_retention_class: graph.defaultPolicies.dataRetentionClass } : {}),
+    },
+  };
+}
+
+export function canonicalWorkflowGraph(graph: WorkflowGraphV1): string {
+  return canonicalJson(graphForStorage(graph));
+}