post_cortex_daemon/daemon/
validate.rs

1// Copyright (c) 2025 Julius ML
2// MIT License
3
4//! Custom validation layer for MCP tool parameters.
5//!
6//! This module provides business logic validation for tool parameters,
7//! complementing the type coercion layer in `coerce.rs`.
8//!
9//! Validations include:
10//! - UUID format validation
11//! - Enum value validation (interaction_type, scope, etc.)
12//! - Numeric limit validation
13//! - Business rule validation
14
15use crate::daemon::coerce::CoercionError;
16use uuid::Uuid;
17
18/// Validate a session ID is a valid UUID and return the parsed value.
19///
20/// # Arguments
21///
22/// * `session_id` - The session ID string to validate
23///
24/// # Returns
25///
26/// * `Ok(Uuid)` - The parsed UUID if valid
27/// * `Err(CoercionError)` with helpful message if invalid
28///
29/// # Example
30///
31/// ```rust
32/// use post_cortex::daemon::validate::validate_session_id;
33/// use uuid::Uuid;
34///
35/// // Valid UUID
36/// assert!(validate_session_id("60c598e2-d602-4e07-a328-c458006d48c7").is_ok());
37///
38/// // Invalid UUID
39/// assert!(validate_session_id("invalid").is_err());
40/// ```
41pub fn validate_session_id(session_id: &str) -> Result<Uuid, CoercionError> {
42    Uuid::parse_str(session_id).map_err(|_| CoercionError::new(
43        &format!("Invalid UUID format: '{}'", session_id),
44        std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid UUID"),
45        Some(session_id.into()),
46    )
47    .with_parameter_path("session_id".to_string())
48    .with_expected_type("UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (36 chars with hyphens)")
49    .with_hint("Create a session first using the 'session' tool with action='create', or search for existing sessions using 'semantic_search'"))
50}
51
52/// Validate a workspace ID is a valid UUID and return the parsed value.
53///
54/// # Arguments
55///
56/// * `workspace_id` - The workspace ID string to validate
57///
58/// # Returns
59///
60/// * `Ok(Uuid)` - The parsed UUID if valid
61/// * `Err(CoercionError)` with helpful message if invalid
62pub fn validate_workspace_id(workspace_id: &str) -> Result<Uuid, CoercionError> {
63    Uuid::parse_str(workspace_id).map_err(|_| CoercionError::new(
64        &format!("Invalid workspace ID format: '{}'", workspace_id),
65        std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid UUID"),
66        Some(workspace_id.into()),
67    )
68    .with_parameter_path("workspace_id".to_string())
69    .with_expected_type("UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (36 chars with hyphens)")
70    .with_hint("Use the 'manage_workspace' tool with action='list' to see available workspaces, or create one with action='create'"))
71}
72
73/// Valid interaction type values
74pub const VALID_INTERACTION_TYPES: &[&str] = &[
75    "qa",
76    "decision_made",
77    "problem_solved",
78    "code_change",
79    "requirement_added",
80    "concept_defined",
81];
82
83/// Validate an interaction type is one of the valid values.
84///
85/// # Arguments
86///
87/// * `interaction_type` - The interaction type string to validate
88///
89/// # Valid Values
90///
91/// - `qa`: Questions and answers about codebase
92/// - `decision_made`: Architectural decisions and trade-offs
93/// - `problem_solved`: Bug fixes and technical solutions
94/// - `code_change`: Code modifications and refactoring
95/// - `requirement_added`: New requirements or constraints
96/// - `concept_defined`: Technical concepts and patterns explained
97///
98/// # Returns
99///
100/// * `Ok(())` if the interaction type is valid
101/// * `Err(CoercionError)` with helpful message if invalid
102pub fn validate_interaction_type(interaction_type: &str) -> Result<(), CoercionError> {
103    if VALID_INTERACTION_TYPES.contains(&interaction_type.to_lowercase().as_str()) {
104        Ok(())
105    } else {
106        Err(CoercionError::new(
107            &format!("Invalid interaction_type: '{}'", interaction_type),
108            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid type"),
109            Some(interaction_type.into()),
110        )
111        .with_parameter_path("interaction_type".to_string())
112        .with_expected_type(&format!("one of: {}", VALID_INTERACTION_TYPES.join(", ")))
113        .with_hint("Use exact lowercase term with underscores. Valid types: qa, decision_made, problem_solved, code_change, requirement_added, concept_defined"))
114    }
115}
116
117/// Validate a scope value for semantic search.
118///
119/// # Arguments
120///
121/// * `scope` - The scope string to validate
122///
123/// # Valid Values
124///
125/// - `session`: Search within a specific session (requires scope_id)
126/// - `workspace`: Search within a workspace (requires scope_id)
127/// - `global`: Search across all data (default)
128///
129/// # Returns
130///
131/// * `Ok(())` if the scope is valid
132/// * `Err(CoercionError)` with helpful message if invalid
133pub fn validate_scope(scope: &str) -> Result<(), CoercionError> {
134    const VALID_SCOPES: &[&str] = &["session", "workspace", "global"];
135
136    if VALID_SCOPES.contains(&scope.to_lowercase().as_str()) {
137        Ok(())
138    } else {
139        Err(CoercionError::new(
140            &format!("Invalid scope: '{}'", scope),
141            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid scope"),
142            Some(scope.into()),
143        )
144        .with_parameter_path("scope".to_string())
145        .with_expected_type(&format!("one of: {}", VALID_SCOPES.join(", ")))
146        .with_hint("Valid scopes: 'session' (requires scope_id), 'workspace' (requires scope_id), 'global' (default, no scope_id needed)"))
147    }
148}
149
150/// Validate a session action.
151///
152/// # Arguments
153///
154/// * `action` - The action string to validate
155///
156/// # Valid Values
157///
158/// - `create`: Create a new session
159/// - `list`: List all sessions
160///
161/// # Returns
162///
163/// * `Ok(())` if the action is valid
164/// * `Err(CoercionError)` with helpful message if invalid
165pub fn validate_session_action(action: &str) -> Result<(), CoercionError> {
166    const VALID_ACTIONS: &[&str] = &[
167        "create",
168        "list",
169        "load",
170        "search",
171        "update_metadata",
172        "delete",
173    ];
174
175    if VALID_ACTIONS.contains(&action.to_lowercase().as_str()) {
176        Ok(())
177    } else {
178        Err(CoercionError::new(
179            &format!("Invalid action: '{}'", action),
180            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid action"),
181            Some(action.into()),
182        )
183        .with_parameter_path("action".to_string())
184        .with_expected_type(&format!("one of: {}", VALID_ACTIONS.join(", ")))
185        .with_hint("Valid actions: create (name, description), list, load (session_id), search (query), update_metadata (session_id + name/description), delete (session_id)"))
186    }
187}
188
189/// Validate a workspace action.
190///
191/// # Arguments
192///
193/// * `action` - The action string to validate
194///
195/// # Valid Values
196///
197/// - `create`: Create a new workspace
198/// - `list`: List all workspaces
199/// - `get`: Get workspace details
200/// - `delete`: Delete a workspace
201/// - `add_session`: Add a session to a workspace
202/// - `remove_session`: Remove a session from a workspace
203///
204/// # Returns
205///
206/// * `Ok(())` if the action is valid
207/// * `Err(CoercionError)` with helpful message if invalid
208pub fn validate_workspace_action(action: &str) -> Result<(), CoercionError> {
209    const VALID_ACTIONS: &[&str] = &[
210        "create",
211        "list",
212        "get",
213        "delete",
214        "add_session",
215        "remove_session",
216    ];
217
218    if VALID_ACTIONS.contains(&action.to_lowercase().as_str()) {
219        Ok(())
220    } else {
221        Err(CoercionError::new(
222            &format!("Invalid action: '{}'", action),
223            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid action"),
224            Some(action.into()),
225        )
226        .with_parameter_path("action".to_string())
227        .with_expected_type(&format!("one of: {}", VALID_ACTIONS.join(", ")))
228        .with_hint("Valid actions: create (with name/description), list, get (workspace_id), delete (workspace_id), add_session (workspace_id, session_id, role), remove_session (workspace_id, session_id)"))
229    }
230}
231
232/// Validate a session role for workspace membership.
233///
234/// # Arguments
235///
236/// * `role` - The role string to validate
237///
238/// # Valid Values
239///
240/// - `primary`: Primary session for the workspace
241/// - `related`: Related session
242/// - `dependency`: Dependency session
243/// - `shared`: Shared session
244///
245/// # Returns
246///
247/// * `Ok(())` if the role is valid
248/// * `Err(CoercionError)` with helpful message if invalid
249pub fn validate_session_role(role: &str) -> Result<(), CoercionError> {
250    const VALID_ROLES: &[&str] = &["primary", "related", "dependency", "shared"];
251
252    if VALID_ROLES.contains(&role.to_lowercase().as_str()) {
253        Ok(())
254    } else {
255        Err(CoercionError::new(
256            &format!("Invalid role: '{}'", role),
257            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid role"),
258            Some(role.into()),
259        )
260        .with_parameter_path("role".to_string())
261        .with_expected_type(&format!("one of: {}", VALID_ROLES.join(", ")))
262        .with_hint("Valid session roles: primary (main session), related (related context), dependency (required context), shared (shared context)"))
263    }
264}
265
266/// Validate a recency_bias parameter is within acceptable bounds.
267///
268/// The recency_bias parameter controls temporal decay in semantic search. Invalid values
269/// can cause exponential growth (negatives), underflow to zero (extreme values), or
270/// corrupt rankings (NaN, Infinity).
271///
272/// # Arguments
273///
274/// * `recency_bias` - The recency_bias value to validate (None means disabled)
275///
276/// # Returns
277///
278/// * `Ok(Some(value))` - The validated recency_bias value
279/// * `Ok(None)` - If recency_bias was None (disabled)
280/// * `Err(CoercionError)` with helpful message if invalid
281///
282/// # Valid Range
283///
284/// - `[0.0, 10.0]` - 0.0 disables decay, 10.0 is maximum practical decay rate
285/// - Rejects: negative values, NaN, Infinity, NegInfinity
286///
287/// # Example
288///
289/// ```rust
290/// use post_cortex::daemon::validate::validate_recency_bias;
291///
292/// // Valid values
293/// assert_eq!(validate_recency_bias(Some(0.0)).unwrap(), Some(0.0));
294/// assert_eq!(validate_recency_bias(Some(0.5)).unwrap(), Some(0.5));
295/// assert_eq!(validate_recency_bias(Some(10.0)).unwrap(), Some(10.0));
296/// assert_eq!(validate_recency_bias(None).unwrap(), None);
297///
298/// // Invalid values
299/// assert!(validate_recency_bias(Some(-1.0)).is_err());
300/// assert!(validate_recency_bias(Some(f32::NAN)).is_err());
301/// assert!(validate_recency_bias(Some(f32::INFINITY)).is_err());
302/// ```
303pub fn validate_recency_bias(recency_bias: Option<f32>) -> Result<Option<f32>, CoercionError> {
304    const MAX_RECENCY_BIAS: f32 = 10.0;
305    const MIN_RECENCY_BIAS: f32 = 0.0;
306
307    if let Some(value) = recency_bias {
308        if value.is_nan() || value.is_infinite() {
309            return Err(CoercionError::new(
310                "Invalid recency_bias value",
311                std::io::Error::new(std::io::ErrorKind::InvalidInput, "NaN or Infinity not allowed"),
312                Some(serde_json::Value::String(value.to_string())),
313            )
314            .with_parameter_path("recency_bias".to_string())
315            .with_expected_type("finite f32 between 0.0 and 10.0")
316            .with_hint("Use a finite value between 0.0 (disabled) and 10.0 (aggressive decay). Recommended: 0.0-1.0 for most use cases."));
317        }
318        if !(MIN_RECENCY_BIAS..=MAX_RECENCY_BIAS).contains(&value) {
319            return Err(CoercionError::new(
320                "recency_bias out of range",
321                std::io::Error::new(std::io::ErrorKind::InvalidInput, "Value must be between 0.0 and 10.0"),
322                Some(serde_json::Value::String(value.to_string())),
323            )
324            .with_parameter_path("recency_bias".to_string())
325            .with_expected_type("f32 in range [0.0, 10.0]")
326            .with_hint(&format!(
327                "Use recency_bias between {} and {}, or omit for default (0.0 = disabled)",
328                MIN_RECENCY_BIAS, MAX_RECENCY_BIAS
329            )));
330        }
331        Ok(Some(value))
332    } else {
333        Ok(None)
334    }
335}
336
337/// Validate a numeric limit is within acceptable bounds.
338///
339/// This function validates that limit parameters are within safe ranges to prevent
340/// excessive resource consumption while maintaining flexibility for legitimate use cases.
341///
342/// # Arguments
343///
344/// * `limit` - The limit value to validate (None means use default)
345/// * `default` - The default limit value (used when limit is None)
346/// * `max` - The maximum allowed limit value
347///
348/// # Returns
349///
350/// * `Ok(limit_value)` - The limit to use (either the provided value or default)
351/// * `Err(CoercionError)` with helpful message if limit exceeds maximum or is zero
352///
353/// # Example
354///
355/// ```rust
356/// use post_cortex::daemon::validate::validate_limits;
357///
358/// // Valid limit
359/// assert_eq!(validate_limits(Some(5), 10, 100).unwrap(), 5);
360///
361/// // Use default
362/// assert_eq!(validate_limits(None, 10, 100).unwrap(), 10);
363///
364/// // Exceeds maximum
365/// assert!(validate_limits(Some(200), 10, 100).is_err());
366/// ```
367pub fn validate_limits(
368    limit: Option<usize>,
369    default: usize,
370    max: usize,
371) -> Result<usize, CoercionError> {
372    let value = limit.unwrap_or(default);
373    if value > max {
374        Err(CoercionError::new(
375            &format!("Limit {} exceeds maximum of {}", value, max),
376            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Limit too large"),
377            Some(value.into()),
378        )
379        .with_parameter_path("limit".to_string())
380        .with_expected_type(&format!("number between 1 and {}", max))
381        .with_hint(&format!(
382            "Use limit between 1 and {}, or omit for default ({})",
383            max, default
384        )))
385    } else if value == 0 {
386        Err(CoercionError::new(
387            "Limit must be at least 1",
388            std::io::Error::new(std::io::ErrorKind::InvalidInput, "Limit too small"),
389            Some(value.into()),
390        )
391        .with_parameter_path("limit".to_string())
392        .with_expected_type(&format!("number between 1 and {}", max))
393        .with_hint(&format!(
394            "Use limit between 1 and {}, or omit for default ({})",
395            max, default
396        )))
397    } else {
398        Ok(value)
399    }
400}
401
402#[cfg(test)]
403mod tests {
404    use super::*;
405
406    #[test]
407    fn test_validate_session_id_valid() {
408        assert!(validate_session_id("60c598e2-d602-4e07-a328-c458006d48c7").is_ok());
409    }
410
411    #[test]
412    fn test_validate_session_id_invalid() {
413        let result = validate_session_id("invalid");
414        assert!(result.is_err());
415        let error = result.unwrap_err();
416        assert_eq!(error.parameter_path, Some("session_id".to_string()));
417        assert!(error.hint.is_some());
418    }
419
420    #[test]
421    fn test_validate_workspace_id_valid() {
422        assert!(validate_workspace_id("60c598e2-d602-4e07-a328-c458006d48c7").is_ok());
423    }
424
425    #[test]
426    fn test_validate_workspace_id_invalid() {
427        let result = validate_workspace_id("not-a-uuid");
428        assert!(result.is_err());
429        let error = result.unwrap_err();
430        assert_eq!(error.parameter_path, Some("workspace_id".to_string()));
431    }
432
433    #[test]
434    fn test_validate_interaction_type_valid() {
435        assert!(validate_interaction_type("qa").is_ok());
436        assert!(validate_interaction_type("decision_made").is_ok());
437        assert!(validate_interaction_type("problem_solved").is_ok());
438        assert!(validate_interaction_type("code_change").is_ok());
439        assert!(validate_interaction_type("requirement_added").is_ok());
440        assert!(validate_interaction_type("concept_defined").is_ok());
441    }
442
443    #[test]
444    fn test_validate_interaction_type_invalid() {
445        let result = validate_interaction_type("made_decision");
446        assert!(result.is_err());
447        let error = result.unwrap_err();
448        assert_eq!(error.parameter_path, Some("interaction_type".to_string()));
449        assert!(error.hint.unwrap().contains("decision_made"));
450    }
451
452    #[test]
453    fn test_validate_scope_valid() {
454        assert!(validate_scope("session").is_ok());
455        assert!(validate_scope("workspace").is_ok());
456        assert!(validate_scope("global").is_ok());
457    }
458
459    #[test]
460    fn test_validate_scope_invalid() {
461        let result = validate_scope("invalid_scope");
462        assert!(result.is_err());
463        let error = result.unwrap_err();
464        assert_eq!(error.parameter_path, Some("scope".to_string()));
465    }
466
467    #[test]
468    fn test_validate_session_action_valid() {
469        assert!(validate_session_action("create").is_ok());
470        assert!(validate_session_action("list").is_ok());
471    }
472
473    #[test]
474    fn test_validate_session_action_invalid() {
475        // "delete" was added to VALID_ACTIONS in a later refactor; the
476        // test previously asserted that "delete" was rejected, which
477        // became the long-standing baseline failure noted in TODO.md.
478        // Use a genuinely invalid action here.
479        let result = validate_session_action("nuke_everything");
480        assert!(result.is_err());
481        let error = result.unwrap_err();
482        let hint = error.hint.as_ref().unwrap();
483        assert!(hint.contains("create") && hint.contains("list"));
484    }
485
486    #[test]
487    fn test_validate_workspace_action_valid() {
488        assert!(validate_workspace_action("create").is_ok());
489        assert!(validate_workspace_action("list").is_ok());
490        assert!(validate_workspace_action("get").is_ok());
491        assert!(validate_workspace_action("delete").is_ok());
492        assert!(validate_workspace_action("add_session").is_ok());
493        assert!(validate_workspace_action("remove_session").is_ok());
494    }
495
496    #[test]
497    fn test_validate_workspace_action_invalid() {
498        let result = validate_workspace_action("invalid_action");
499        assert!(result.is_err());
500    }
501
502    #[test]
503    fn test_validate_session_role_valid() {
504        assert!(validate_session_role("primary").is_ok());
505        assert!(validate_session_role("related").is_ok());
506        assert!(validate_session_role("dependency").is_ok());
507        assert!(validate_session_role("shared").is_ok());
508    }
509
510    #[test]
511    fn test_validate_session_role_invalid() {
512        let result = validate_session_role("admin");
513        assert!(result.is_err());
514        let error = result.unwrap_err();
515        assert_eq!(error.parameter_path, Some("role".to_string()));
516        assert!(error.hint.unwrap().contains("primary"));
517    }
518
519    #[test]
520    fn test_validate_limits_within_bounds() {
521        assert_eq!(validate_limits(Some(5), 10, 100).unwrap(), 5);
522        assert_eq!(validate_limits(Some(10), 10, 100).unwrap(), 10);
523        assert_eq!(validate_limits(Some(100), 10, 100).unwrap(), 100);
524    }
525
526    #[test]
527    fn test_validate_limits_use_default() {
528        assert_eq!(validate_limits(None, 10, 100).unwrap(), 10);
529        assert_eq!(validate_limits(None, 50, 100).unwrap(), 50);
530    }
531
532    #[test]
533    fn test_validate_limits_exceeds_maximum() {
534        let result = validate_limits(Some(200), 10, 100);
535        assert!(result.is_err());
536        let error = result.unwrap_err();
537        assert_eq!(error.parameter_path, Some("limit".to_string()));
538        assert!(error.message.contains("exceeds maximum"));
539    }
540
541    #[test]
542    fn test_validate_limits_zero() {
543        let result = validate_limits(Some(0), 10, 100);
544        assert!(result.is_err());
545        let error = result.unwrap_err();
546        assert!(error.message.contains("at least 1"));
547    }
548
549    #[test]
550    fn test_validate_recency_bias_valid() {
551        // Valid values
552        assert_eq!(validate_recency_bias(Some(0.0)).unwrap(), Some(0.0));
553        assert_eq!(validate_recency_bias(Some(0.5)).unwrap(), Some(0.5));
554        assert_eq!(validate_recency_bias(Some(1.0)).unwrap(), Some(1.0));
555        assert_eq!(validate_recency_bias(Some(10.0)).unwrap(), Some(10.0));
556    }
557
558    #[test]
559    fn test_validate_recency_bias_none() {
560        assert_eq!(validate_recency_bias(None).unwrap(), None);
561    }
562
563    #[test]
564    fn test_validate_recency_bias_negative() {
565        let result = validate_recency_bias(Some(-1.0));
566        assert!(result.is_err());
567        let error = result.unwrap_err();
568        assert_eq!(error.parameter_path, Some("recency_bias".to_string()));
569        assert!(error.message.contains("out of range"));
570    }
571
572    #[test]
573    fn test_validate_recency_bias_nan() {
574        let result = validate_recency_bias(Some(f32::NAN));
575        assert!(result.is_err());
576        let error = result.unwrap_err();
577        assert_eq!(error.parameter_path, Some("recency_bias".to_string()));
578        assert!(error.message.contains("Invalid recency_bias value"));
579    }
580
581    #[test]
582    fn test_validate_recency_bias_infinity() {
583        let result = validate_recency_bias(Some(f32::INFINITY));
584        assert!(result.is_err());
585        let error = result.unwrap_err();
586        assert!(error.message.contains("NaN or Infinity not allowed"));
587    }
588
589    #[test]
590    fn test_validate_recency_bias_exceeds_maximum() {
591        let result = validate_recency_bias(Some(100.0));
592        assert!(result.is_err());
593        let error = result.unwrap_err();
594        assert!(error.message.contains("out of range"));
595        assert_eq!(error.parameter_path, Some("recency_bias".to_string()));
596    }
597}
post_cortex_daemon/daemon/validate.rs

post_cortex_daemon/daemon/
validate.rs
