@ema.co/mcp-toolkit 2026.1.27 → 2026.1.28-2

package/dist/sdk/workflow-static-validator.js

@@ -0,0 +1,291 @@
+/**
+ * Static Workflow Validator
+ *
+ * Implements Go validator's static validation logic:
+ * - Path enumeration
+ * - Required output validation (all paths produce all named results)
+ * - Multiple writers detection
+ * - Response/abstain validation
+ * - Category hierarchy validation
+ *
+ * Based on: workflow-engine/pkg/engine/validator.go
+ */
+import { enumeratePaths } from "./workflow-path-enumerator.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Validation Function
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Perform static validation on a workflow.
+ *
+ * Only validates workflows with named results (resultMappings).
+ * If no named results, returns valid (matching Go validator behavior).
+ */
+export function validateWorkflowStatic(workflow, options) {
+    // Collect all errors (path-dependent and global)
+    const errors = [];
+    const warnings = [];
+    const info = [];
+    // Validate categorizers globally (not dependent on named results)
+    const categorizerErrors = validateAllCategorizers(workflow);
+    errors.push(...categorizerErrors.filter(e => e.severity === "critical"));
+    warnings.push(...categorizerErrors.filter(e => e.severity === "warning"));
+    info.push(...categorizerErrors.filter(e => e.severity === "info"));
+    // Static validation only applies to workflows with named results
+    if (!workflow.resultMappings || workflow.resultMappings.length === 0) {
+        // Count errors by type
+        const errorsByType = {
+            required_output_not_produced: 0,
+            multiple_writers: 0,
+            missing_response_or_abstain_reason: 0,
+            category_hierarchy_violation: errors.filter(e => e.type === "category_hierarchy_violation").length,
+        };
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            info,
+            summary: {
+                total_paths: 0,
+                valid_paths: 0,
+                invalid_paths: 0,
+                errors_by_type: errorsByType,
+            },
+        };
+    }
+    // Enumerate all execution paths
+    const paths = enumeratePaths(workflow, options);
+    // Extract named results from resultMappings
+    const namedResults = extractNamedResults(workflow.resultMappings);
+    // Validate each path
+    for (const path of paths) {
+        const pathErrors = validatePath(path, workflow, namedResults);
+        errors.push(...pathErrors.filter(e => e.severity === "critical"));
+        warnings.push(...pathErrors.filter(e => e.severity === "warning"));
+        info.push(...pathErrors.filter(e => e.severity === "info"));
+    }
+    // Count errors by type
+    const errorsByType = {
+        required_output_not_produced: errors.filter(e => e.type === "required_output_not_produced").length,
+        multiple_writers: errors.filter(e => e.type === "multiple_writers").length,
+        missing_response_or_abstain_reason: errors.filter(e => e.type === "missing_response_or_abstain_reason").length,
+        category_hierarchy_violation: errors.filter(e => e.type === "category_hierarchy_violation").length,
+    };
+    const validPaths = paths.filter(p => !p.validation_failed).length;
+    const invalidPaths = paths.filter(p => p.validation_failed).length;
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        info,
+        summary: {
+            total_paths: paths.length,
+            valid_paths: validPaths,
+            invalid_paths: invalidPaths,
+            errors_by_type: errorsByType,
+        },
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Path Validation
+// ─────────────────────────────────────────────────────────────────────────────
+function validatePath(path, workflow, namedResults) {
+    const errors = [];
+    // 1. Check required outputs
+    errors.push(...validateRequiredOutputs(path, workflow, namedResults));
+    // 2. Check multiple writers
+    errors.push(...validateMultipleWriters(path, workflow, namedResults));
+    // 3. Check response/abstain
+    errors.push(...validateResponseOrAbstain(path, workflow));
+    // 4. Check category hierarchy (if path has categorizer)
+    errors.push(...validateCategoryHierarchy(path, workflow));
+    return errors;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation: Required Outputs
+// ─────────────────────────────────────────────────────────────────────────────
+function validateRequiredOutputs(path, workflow, namedResults) {
+    const errors = [];
+    // Get outputs produced on this path
+    const producedOutputs = new Set(Object.keys(path.final_outputs));
+    // Check each named result
+    for (const namedResult of namedResults) {
+        if (!producedOutputs.has(namedResult)) {
+            // Extract node and output from named result format: "nodeId.outputName"
+            const [nodeId, outputName] = namedResult.split(".");
+            errors.push({
+                type: "required_output_not_produced",
+                rule_id: "required_output_all_paths",
+                severity: "critical",
+                location: {
+                    path: path.completed_actions,
+                    category: path.chosen_enumerable_value,
+                    named_result: namedResult,
+                    action_name: path.action_name,
+                    output_name: path.enumerable_output,
+                    output_value: path.chosen_enumerable_value,
+                },
+                what: `Path '${formatPathName(path)}' does not produce required output '${namedResult}'`,
+                why: `All execution paths from trigger must produce all named results. The path '${formatPathName(path)}' ends at '${path.action_name}' without producing '${namedResult}'.`,
+                how_to_fix: `Add a node that produces '${namedResult}' to the '${formatPathName(path)}' path. Connect the node's '${outputName}' output to WORKFLOW_OUTPUT via resultMappings.`,
+                rule_reference: "ema://validation/rules#required_output_all_paths",
+                examples: {
+                    bad: `trigger → ${path.completed_actions.join(" → ")} → (no ${outputName})`,
+                    good: `trigger → ${path.completed_actions.join(" → ")} → ${nodeId} → WORKFLOW_OUTPUT`,
+                },
+            });
+        }
+    }
+    return errors;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation: Multiple Writers
+// ─────────────────────────────────────────────────────────────────────────────
+function validateMultipleWriters(path, workflow, namedResults) {
+    const errors = [];
+    // Build map: namedResult -> nodes that produce it
+    const producers = new Map();
+    for (const namedResult of namedResults) {
+        const [nodeId] = namedResult.split(".");
+        // Check if this node is in the path
+        if (path.completed_actions.includes(nodeId)) {
+            if (!producers.has(namedResult)) {
+                producers.set(namedResult, []);
+            }
+            producers.get(namedResult).push(nodeId);
+        }
+    }
+    // Check for multiple producers
+    for (const [namedResult, nodeIds] of producers.entries()) {
+        if (nodeIds.length > 1) {
+            errors.push({
+                type: "multiple_writers",
+                rule_id: "single_writer_per_output",
+                severity: "critical",
+                location: {
+                    path: path.completed_actions,
+                    category: path.chosen_enumerable_value,
+                    named_result: namedResult,
+                    action_name: path.action_name,
+                },
+                what: `Multiple nodes produce '${namedResult}' on path '${formatPathName(path)}'`,
+                why: `A single named result can only have one producer per execution path. The path '${formatPathName(path)}' has both '${nodeIds[0]}' and '${nodeIds[1]}' producing '${namedResult}'.`,
+                how_to_fix: `Ensure only one node produces '${namedResult}' on the '${formatPathName(path)}' path. Either remove one of the producers or use different named results for each node.`,
+                rule_reference: "ema://validation/rules#single_writer_per_output",
+            });
+        }
+    }
+    return errors;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation: Response or Abstain
+// ─────────────────────────────────────────────────────────────────────────────
+function validateResponseOrAbstain(path, workflow) {
+    const errors = [];
+    // Check if path produces any response
+    const responseNodes = ["respond_with_sources", "call_llm", "fixed_response"];
+    const hasResponse = path.completed_actions.some(actionId => {
+        const node = workflow.nodes.find(n => n.id === actionId);
+        return node && responseNodes.includes(node.actionType);
+    });
+    // Check if path has abstain reason
+    // TODO: How is abstain reason defined? Need to check Go code
+    const hasAbstain = false; // Placeholder
+    if (!hasResponse && !hasAbstain) {
+        errors.push({
+            type: "missing_response_or_abstain_reason",
+            rule_id: "response_or_abstain_required",
+            severity: "critical",
+            location: {
+                path: path.completed_actions,
+                category: path.chosen_enumerable_value,
+                action_name: path.action_name,
+            },
+            what: `Path '${formatPathName(path)}' does not produce a response and has no abstain reason`,
+            why: `Every execution path must either produce a user-visible response or explicitly abstain with a reason. The path '${formatPathName(path)}' ends at '${path.action_name}' without a response node and no abstain reason is specified.`,
+            how_to_fix: `Either add a response node (respond_with_sources, call_llm, or fixed_response) to the '${formatPathName(path)}' path, or add an abstain reason explaining why this path doesn't respond.`,
+            rule_reference: "ema://validation/rules#response_or_abstain_required",
+        });
+    }
+    return errors;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation: Category Hierarchy
+// ─────────────────────────────────────────────────────────────────────────────
+function validateCategoryHierarchy(path, workflow) {
+    const errors = [];
+    // Find categorizer nodes in path
+    const categorizers = path.completed_actions
+        .map(actionId => workflow.nodes.find(n => n.id === actionId))
+        .filter((node) => node !== undefined &&
+        (node.actionType === "chat_categorizer" || node.actionType === "text_categorizer"));
+    for (const categorizer of categorizers) {
+        // Check if categorizer has Fallback category
+        const hasFallback = categorizer.categories?.some(cat => cat.name === "Fallback" || cat.name === "Other");
+        if (!hasFallback) {
+            errors.push({
+                type: "category_hierarchy_violation",
+                rule_id: "category_hierarchy_valid",
+                severity: "critical",
+                location: {
+                    node_id: categorizer.id,
+                    path: path.completed_actions,
+                },
+                what: `Categorizer '${categorizer.id}' does not have a Fallback category`,
+                why: "Every categorizer must have a Fallback category to handle unrecognized intents. Without it, some user queries will have no handler.",
+                how_to_fix: `Add a Fallback category to the categorizer '${categorizer.id}' with description 'For unclear or other requests'.`,
+                rule_reference: "ema://validation/rules#category_hierarchy_valid",
+            });
+        }
+        // TODO: Check for category hierarchy violations
+        // Need to analyze named_result_agent_assist_validator.go for exact rules
+    }
+    return errors;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Functions
+// ─────────────────────────────────────────────────────────────────────────────
+function extractNamedResults(resultMappings) {
+    const namedResults = new Set();
+    for (const mapping of resultMappings) {
+        const namedResult = `${mapping.nodeId}.${mapping.output}`;
+        namedResults.add(namedResult);
+    }
+    return namedResults;
+}
+function formatPathName(path) {
+    if (path.chosen_enumerable_value) {
+        return path.chosen_enumerable_value;
+    }
+    if (path.action_name) {
+        return path.action_name;
+    }
+    return "Unknown";
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Global Categorizer Validation (not path-dependent)
+// ─────────────────────────────────────────────────────────────────────────────
+function validateAllCategorizers(workflow) {
+    const errors = [];
+    // Find all categorizer nodes in workflow
+    const categorizers = workflow.nodes.filter(node => node.actionType === "chat_categorizer" ||
+        node.actionType === "text_categorizer");
+    for (const categorizer of categorizers) {
+        // Check if categorizer has Fallback category
+        const hasFallback = categorizer.categories?.some(cat => cat.name === "Fallback" || cat.name === "Other");
+        if (!hasFallback) {
+            errors.push({
+                type: "category_hierarchy_violation",
+                rule_id: "category_hierarchy_valid",
+                severity: "critical",
+                location: {
+                    node_id: categorizer.id,
+                },
+                what: `Categorizer '${categorizer.id}' does not have a Fallback category`,
+                why: "Every categorizer must have a Fallback category to handle unrecognized intents. Without it, some user queries will have no handler.",
+                how_to_fix: `Add a Fallback category to the categorizer '${categorizer.id}' with description 'For unclear or other requests'.`,
+                rule_reference: "ema://validation/rules#category_hierarchy_valid",
+            });
+        }
+    }
+    return errors;
+}

package/dist/sdk/workflow-validation-types.js

@@ -0,0 +1,7 @@
+/**
+ * Validation Types - Enhanced Error Format
+ *
+ * Defines TypeScript interfaces for validation errors with enhanced
+ * "what, why, how" format for clear, actionable error messages.
+ */
+export {};

package/docs/README.md

@@ -0,0 +1,14 @@
+# Deprecated
+
+> **This directory is deprecated.** Public documentation has moved to `.context/public/guides/`.
+
+## Moved files
+
+- `ema-user-guide.md` → `.context/public/guides/ema-user-guide.md`
+- `mcp-tools-guide.md` → `.context/public/guides/mcp-tools-guide.md`
+- `dashboard-operations.md` → `.context/public/guides/dashboard-operations.md`
+- `email-patterns.md` → `.context/public/guides/email-patterns.md`
+
+## Future
+
+This directory may be re-added as a symlink to internal docs once cutover is verified.

package/docs/go-validator-analysis.md

@@ -0,0 +1,323 @@
+# Go Validator Analysis
+
+**Date**: 2026-01-27  
+**Source**: `workflow-engine/pkg/engine/validator.go`  
+**Purpose**: Detailed analysis of Go validator implementation
+
+---
+
+## Architecture Overview
+
+### Components
+
+1. **Validator Interface**: `Validator.Validate(ctx, workflow)`
+2. **Local Validator**: Implements validator interface
+3. **Path Enumeration**: `enumerateAndValidatePaths()` - Core algorithm
+4. **Static Validation Strategy**: `StaticValidationStrategy` - Simulation strategy
+5. **Validation Session**: `ValidationWorkflowSession` - Session state management
+
+---
+
+## Core Algorithm: Path Enumeration
+
+### Algorithm Flow
+
+```
+1. Create initial validation session
+   └─> Dummy inputs, empty state
+
+2. Queue initial session
+   └─> sessionsToProcess = [initialSession]
+
+3. While queue not empty:
+   a. Dequeue session
+   b. Run validation on session
+      └─> session.RunValidation(ctx)
+   
+   c. Handle result:
+      ├─> OutcomeBranch:
+      │   └─> For each possible value:
+      │       ├─> Fork session
+      │       ├─> Plug chosen value
+      │       ├─> Mark action complete
+      │       └─> Queue forked session
+      │
+      └─> OutcomeCompleted:
+          ├─> Track completed path
+          ├─> Validate named results
+          ├─> Apply custom validators
+          └─> Store in completedSessionMap
+
+4. Cleanup incomplete sessions
+5. Return completedSessionMap
+```
+
+### Key Data Structures
+
+#### completedPathInfo
+
+```go
+type completedPathInfo struct {
+    CompletedActions []string              // Actions executed (topological order)
+    FinalOutputs map[string]*pb.Value      // Final outputs produced
+    ActionName string                      // Path identifier
+    EnumerableOutput *string               // Branching output name (if branched)
+    ChosenEnumerableValue *string          // Chosen value (if branched)
+    NamedResultsValidationsFailed bool     // Validation failure flag
+}
+```
+
+#### BranchPointInfo
+
+```go
+type BranchPointInfo struct {
+    ActionThatBranched *ActionNode         // The branching action
+    BranchingOutputName string             // Output that branches
+    PossibleValues []*pb.Value             // All possible values
+    ChosenValue *pb.Value                  // Value chosen for this fork
+}
+```
+
+---
+
+## Static Validation Strategy
+
+### Purpose
+
+Simulates workflow execution without actually running actions:
+- Produces dummy outputs for non-branching actions
+- Returns branching information for branching actions
+- Never calls actual action code
+
+### Key Methods
+
+#### BindWorkflowInputs
+
+- Generates type-aware dummy values for all workflow inputs
+- Binds to input bindings
+- Validates type compatibility
+
+#### BindWidgetConfigs
+
+- Generates type-aware dummy values for all widget configs
+- Binds to widget config bindings
+- Validates type compatibility
+
+#### ExecuteAction
+
+**For Branching Actions**:
+- Returns `ActionExecutionResult{Outputs: nil, BranchPoint: &branchPoint}`
+- BranchPoint contains: action, output name, possible values
+
+**For Non-Branching Actions**:
+- Generates type-aware dummy outputs for all outputs
+- Marks action as completed
+- Returns `ActionExecutionResult{Outputs: outputs}`
+
+### Enumerable Output Detection
+
+```go
+func isOutputTypeEnumerable(outputDef *pb.ActionType_OutputDef) bool {
+    if outputDef.GetArgumentType().GetStatic() == nil {
+        return false
+    }
+    return outputDef.GetArgumentType().GetStatic().GetEnumType() != nil ||
+           outputDef.GetArgumentType().GetStatic().GetWellKnownType() == pb.WellKnownType_WELL_KNOWN_TYPE_BOOL
+}
+```
+
+**Enumerable Types**:
+- Enum types (categorizer categories)
+- Boolean types (true/false)
+
+**Non-Enumerable Types**:
+- Strings, numbers, complex types
+- Unknown types (dynamic)
+
+---
+
+## Path Forking Logic
+
+### forkForBranching Function
+
+```go
+func forkForBranching(
+    session ValidationWorkflowSession,
+    branchInfo *BranchPointInfo,
+    branchValue *pb.Value,
+) (ValidationWorkflowSession, error)
+```
+
+**Steps**:
+1. Deep copy session
+2. Create fake outputs for branching action:
+   - For branching output: Use chosen value
+   - For other outputs: Generate type-aware dummy values
+3. Merge fake outputs into session
+4. Mark branching action as completed
+5. Update last encountered branching action in session
+6. Return forked session
+
+### Session State Management
+
+- Each forked session is independent
+- State includes: completed actions, available outputs, action states
+- Forking preserves parent state, then modifies for chosen branch
+
+---
+
+## Named Results Validation
+
+### Validation Points
+
+1. **Required Output Check**: All named results produced on all paths
+2. **Multiple Writers Check**: No duplicate producers on same path
+3. **Response/Abstain Check**: Every path has response or abstain
+4. **Category Hierarchy Check**: Categorizer structure valid
+
+### Where Validation Happens
+
+Validation occurs in `local_executor.go` during path completion:
+- `AddNamedResultError()` called when validation fails
+- Errors stored in workflow graph
+- Workflow marked as non-runnable if errors exist
+
+---
+
+## Error Reporting
+
+### Error Storage
+
+Errors stored in workflow graph:
+```go
+workflow.AddNamedResultError(errorType, namedResultName, pathIdentifier, message)
+```
+
+### Error Structure
+
+```go
+type WorkflowError_NamedResultError struct {
+    ErrorType pb.WorkflowError_ResultErrorType
+    NamedResultName string
+    PathIdentifier *WorkflowError_ActionOutput
+    Message string
+}
+```
+
+### Path Identifier Format
+
+```go
+type WorkflowError_ActionOutput struct {
+    ActionName string      // Always present
+    OutputName string      // Only for branching paths
+    OutputValue string     // Only for branching paths
+}
+```
+
+---
+
+## Custom Validators
+
+### Interface
+
+```go
+type CustomNamedResultValidator interface {
+    Validate(workflow *WorkflowGraph, pathInfo *completedPathInfo) error
+}
+```
+
+### Implementation Example
+
+`named_result_agent_assist_validator.go`:
+- Validates Agent Assist persona-specific rules
+- Checks category hierarchy
+- Checks response/abstain for Agent Assist patterns
+
+### Integration
+
+- Retrieved via `GetCustomValidatorForPersonaType()`
+- Called after general validations pass
+- Can add persona-specific errors
+
+---
+
+## Performance Characteristics
+
+### Complexity
+
+- **Time**: O(P * A) where P = paths, A = actions per path
+- **Space**: O(P * A) for session storage
+
+### Optimization Opportunities
+
+1. **Early Pruning**: Stop if path already invalid
+2. **Path Caching**: Cache results for unchanged workflows
+3. **Parallel Enumeration**: Enumerate paths in parallel (future)
+
+---
+
+## Test Coverage
+
+### Test Files
+
+- `local_executor_static_validation_test.go` - Core validation tests
+- `local_executor_named_outputs_test.go` - Named results tests
+- `local_enumerator_test.go` - Path enumeration tests
+
+### Test Patterns
+
+1. **Simple workflows**: Linear, no branching
+2. **Categorizer workflows**: Single categorizer, multiple branches
+3. **Nested branching**: Multiple categorizers in sequence
+4. **Error cases**: Missing outputs, multiple writers, etc.
+
+---
+
+## Key Insights
+
+### 1. Dummy Value Generation
+
+- All dummy values are **type-aware**
+- Uses `util.CreateTypeAwareDummyValue()` for type compatibility
+- Preserves type information for validation
+
+### 2. Branching Detection
+
+- Only enum and boolean outputs are considered enumerable
+- Other types cannot be used for path enumeration
+- Unknown types default to non-branching
+
+### 3. Path Identification
+
+- Paths are identified by **last branching action + value** OR **last action**
+- This allows precise error reporting
+- Path identifier used in error messages
+
+### 4. Session Management
+
+- Sessions are deep copied when forking
+- Each session maintains independent state
+- Completed sessions stored in map for analysis
+
+---
+
+## Implementation Notes for TypeScript
+
+### Must Implement
+
+1. **Path Enumeration**: Topological sort + DFS + forking
+2. **Dummy Value Generation**: Type-aware dummy values
+3. **Branching Detection**: Enum and boolean outputs
+4. **Session Management**: Deep copying, state tracking
+5. **Error Reporting**: Same error types and path identifiers
+
+### Can Enhance
+
+1. **Error Messages**: Add what/why/how format
+2. **Performance**: Add caching, early pruning
+3. **Additional Validations**: Add more checks (document as extensions)
+
+---
+
+**Status**: ✅ Analysis complete  
+**Next**: Use this analysis to implement TypeScript validator