groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T3S1/research/external_best_practices.md

@@ -0,0 +1,265 @@
+# External Best Practices for Workflow Name Validation
+
+## Industry Standards Comparison
+
+### 1. Kubernetes Naming Standards
+**Source:** [Kubernetes Documentation - Names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/)
+
+| Requirement | Value |
+|-------------|-------|
+| Max Length | 253 characters |
+| Allowed Characters | Lowercase alphanumeric, `-`, `.` |
+| Must Start/End With | Alphanumeric |
+| Pattern | `[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*` |
+| Rule | Must be valid DNS subdomain name |
+
+### 2. Apache Airflow DAG Naming
+**Source:** [Airflow DAG Documentation](https://airflow.apache.org/docs/apache-airflow/stable/concepts/dags.html)
+
+| Requirement | Value |
+|-------------|-------|
+| Characters | Alphanumeric, underscores only |
+| Spaces | Not allowed |
+| Pattern | `^[a-zA-Z0-9_]+$` |
+| Uniqueness | Required across all DAGs |
+| Case | Case-sensitive |
+| File Naming | Must match Python module naming (no hyphens) |
+
+### 3. AWS Step Functions State Machine Names
+**Source:** [AWS Step Functions Documentation](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-state-machine-structure.html)
+
+| Requirement | Value |
+|-------------|-------|
+| Min Length | 1 character |
+| Max Length | 80 characters |
+| Allowed Characters | Alphanumeric, hyphens, underscores |
+| Pattern | `^[a-zA-Z0-9_-]+$` |
+| Uniqueness | Required within account/region |
+| Case | Case-insensitive |
+
+### 4. GitHub Actions Workflow Names
+**Source:** [GitHub Actions Documentation](https://docs.github.com/en/actions/using-workflows)
+
+| Requirement | Value |
+|-------------|-------|
+| Characters | Most printable characters allowed |
+| Purpose | Display name for UI |
+| Format | String value in YAML |
+| Fallback | Uses filename if name omitted |
+
+### 5. Temporal Workflow Names
+**Source:** [Temporal TypeScript Documentation](https://docs.temporal.io/docs/typescript/workflows)
+
+| Requirement | Value |
+|-------------|-------|
+| Pattern | Valid TypeScript identifier |
+| Regex | `^[a-zA-Z_$][a-zA-Z0-9_$]*$` |
+| Convention | PascalCase or camelCase |
+| Uniqueness | Scoped to namespace/task queue |
+
+## Common Validation Patterns
+
+### Pattern 1: Strict Identifier (Kubernetes-style)
+```typescript
+const STRICT_IDENTIFIER = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$/;
+
+function validateStrict(name: string): boolean {
+  return (
+    name.length >= 1 &&
+    name.length <= 253 &&
+    STRICT_IDENTIFIER.test(name)
+  );
+}
+```
+
+### Pattern 2: Alphanumeric with Underscores (Airflow-style)
+```typescript
+const SNAKE_CASE_IDENTIFIER = /^[a-zA-Z0-9_]+$/;
+
+function validateSnakeCase(name: string): boolean {
+  return name.length > 0 && SNAKE_CASE_IDENTIFIER.test(name);
+}
+```
+
+### Pattern 3: Flexible Identifier (AWS-style)
+```typescript
+const FLEXIBLE_IDENTIFIER = /^[a-zA-Z0-9_-]+$/;
+
+function validateFlexible(name: string): boolean {
+  return (
+    name.length >= 1 &&
+    name.length <= 80 &&
+    FLEXIBLE_IDENTIFIER.test(name)
+  );
+}
+```
+
+### Pattern 4: TypeScript/JavaScript Identifier
+```typescript
+const JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+function validateJSIdentifier(name: string): boolean {
+  return JS_IDENTIFIER.test(name);
+}
+```
+
+## Best Practice Summary
+
+### Length Limits
+| System | Min | Max | Recommendation for Groundswell |
+|--------|-----|-----|--------------------------------|
+| Kubernetes | 1 | 253 | |
+| Airflow | - | - | |
+| AWS | 1 | 80 | **1-100** (reasonable balance) |
+| GitHub | - | - | |
+
+### Character Sets
+| System | Characters | Restrictiveness |
+|--------|------------|-----------------|
+| Kubernetes | `[a-z0-9.-]` | Most restrictive |
+| Airflow | `[a-zA-Z0-9_]` | Moderate |
+| AWS | `[a-zA-Z0-9_-]` | Moderate |
+| GitHub | Most printable | Permissive |
+| Temporal | `[a-zA-Z0-9_$]` | Language-specific |
+
+### Common Rules Across All Systems
+
+1. **Non-empty:** All systems require at least 1 character
+2. **No spaces:** Spaces are universally rejected
+3. **ASCII-only:** Unicode not typically allowed
+4. **Uniqueness:** Required within appropriate scope
+5. **No reserved words:** System keywords avoided
+
+## TypeScript Implementation Patterns
+
+### Basic Validation Function
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+function validateWorkflowName(name: unknown): ValidationResult {
+  // Type check
+  if (typeof name !== 'string') {
+    return { valid: false, error: 'Workflow name must be a string' };
+  }
+
+  // Empty check
+  if (name.length === 0) {
+    return { valid: false, error: 'Workflow name cannot be empty' };
+  }
+
+  // Whitespace check
+  if (name.trim().length === 0) {
+    return { valid: false, error: 'Workflow name cannot be whitespace only' };
+  }
+
+  // Length check
+  if (name.length > 100) {
+    return { valid: false, error: 'Workflow name cannot exceed 100 characters' };
+  }
+
+  return { valid: true };
+}
+```
+
+### Branded Type Pattern (Type-safe)
+```typescript
+// Type for validated workflow names
+type WorkflowName = string & { readonly __brand: unique symbol };
+
+function toWorkflowName(name: unknown): WorkflowName {
+  const result = validateWorkflowName(name);
+  if (!result.valid) {
+    throw new Error(result.error);
+  }
+  return name as WorkflowName;
+}
+
+// Usage in Workflow class
+class Workflow {
+  constructor(name: WorkflowName | string) {
+    // If passed as string, validate
+    const validated = typeof name === 'string' ? toWorkflowName(name) : name;
+    this.node = { name: validated, ... };
+  }
+}
+```
+
+### Regex-based Validation
+```typescript
+// Recommended pattern for Groundswell
+const WORKFLOW_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$/;
+
+// Or simpler: just ensure non-empty with no control characters
+const SIMPLE_PATTERN = /^[^\x00-\x1F\x7F]+$/;
+
+function validateWithPattern(name: string): boolean {
+  return (
+    name.length >= 1 &&
+    name.length <= 100 &&
+    SIMPLE_PATTERN.test(name)
+  );
+}
+```
+
+## Recommendation for Groundswell
+
+Based on industry standards and codebase patterns:
+
+### Option A: Minimal Validation (Recommended for initial implementation)
+```typescript
+// Rules:
+// 1. Must be a string
+// 2. Must be non-empty after trimming
+// 3. No length limit (or very generous limit)
+
+function validateWorkflowName(name: unknown): string {
+  if (typeof name !== 'string') {
+    throw new Error('Workflow name must be a string');
+  }
+  if (name.trim().length === 0) {
+    throw new Error('Workflow name cannot be empty or whitespace only');
+  }
+  return name.trim();
+}
+```
+
+### Option B: Moderate Validation (Follows AWS/Airflow style)
+```typescript
+// Rules:
+// 1. Non-empty string
+// 2. 1-100 characters
+// 3. Alphanumeric, hyphens, underscores only
+// 4. Must start/end with alphanumeric
+
+const WORKFLOW_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$/;
+
+function validateWorkflowName(name: unknown): string {
+  if (typeof name !== 'string') {
+    throw new Error('Workflow name must be a string');
+  }
+  const trimmed = name.trim();
+  if (trimmed.length === 0 || trimmed.length > 100) {
+    throw new Error('Workflow name must be 1-100 characters');
+  }
+  if (!WORKFLOW_NAME_PATTERN.test(trimmed)) {
+    throw new Error(
+      'Workflow name must contain only alphanumeric characters, hyphens, and underscores, ' +
+      'and must start and end with an alphanumeric character'
+    );
+  }
+  return trimmed;
+}
+```
+
+## External References
+
+| System | Documentation URL |
+|--------|-------------------|
+| Kubernetes Names | https://kubernetes.io/docs/concepts/overview/working-with-objects/names/ |
+| Apache Airflow DAGs | https://airflow.apache.org/docs/apache-airflow/stable/concepts/dags.html |
+| AWS Step Functions | https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-state-machine-structure.html |
+| GitHub Actions | https://docs.github.com/en/actions/using-workflows |
+| Temporal Workflows | https://docs.temporal.io/docs/typescript/workflows |

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T3S1/research/validation_patterns.md

@@ -0,0 +1,273 @@
+# Validation Patterns in Groundswell Codebase
+
+## Overview
+
+This document catalogs validation patterns used throughout the Groundswell codebase to inform the implementation of workflow name validation.
+
+## Parameter Validation Patterns
+
+### Pattern 1: Required Context Validation
+**File:** `src/context.ts:42-51`
+
+```typescript
+export function requireExecutionContext(
+  operation: string
+): AgentExecutionContext {
+  const context = executionContext.getStore();
+  if (!context) {
+    throw new Error(
+      `${operation} called outside of workflow context. ` +
+      `Agent/Prompt operations must be executed within a workflow step.`
+    );
+  }
+  return context;
+}
+```
+
+**Key Characteristics:**
+- Null/undefined check with `!context`
+- Descriptive error message with context
+- Includes operation name in error
+- Suggests remedy ("must be executed within...")
+
+### Pattern 2: Unique Registration Validation
+**File:** `src/core/mcp-handler.ts:62-67`
+
+```typescript
+public registerServer(server: MCPServer): void {
+  if (this.servers.has(server.name)) {
+    throw new Error(`MCP server '${server.name}' is already registered`);
+  }
+  this.servers.set(server.name, server);
+}
+```
+
+**Key Characteristics:**
+- Pre-operation validation check
+- Uses `has()` to check existence
+- Error includes the conflicting value
+- Specific error message for clarity
+
+### Pattern 3: Circular Reference Detection
+**File:** `src/core/workflow.ts:186-191`
+
+```typescript
+if (visited.has(current)) {
+  throw new Error('Circular parent-child relationship detected');
+}
+```
+
+**Key Characteristics:**
+- Cycle detection using Set
+- Concise error message
+- Uses generic error type (not custom)
+
+### Pattern 4: Parent Validation with Detailed Error
+**File:** `src/core/workflow.ts:272-279`
+
+```typescript
+if (child.parent !== null && child.parent !== this) {
+  const errorMessage =
+    `Child '${child.node.name}' already has a parent '${child.parent.node.name}'. ` +
+    `A workflow can only have one parent. ` +
+    `Use detachChild() on '${child.parent.node.name}' first if you need to reparent.`;
+  console.error(errorMessage);
+  throw new Error(errorMessage);
+}
+```
+
+**Key Characteristics:**
+- Multi-line error message for clarity
+- Includes actual values (names)
+- Explains the constraint
+- Provides actionable guidance
+- Logs to console.error before throwing
+
+### Pattern 5: Input Existence Check
+**File:** `src/core/workflow.ts:320-323`
+
+```typescript
+if (!childOrName) {
+  throw new Error('Child workflow or name is required');
+}
+```
+
+**Key Characteristics:**
+- Simple existence check
+- Clear error message
+- Uses negated condition
+
+## Test Patterns for Validation
+
+### Pattern 1: TDD-style Error Testing
+**File:** `src/__tests__/adversarial/circular-reference.test.ts:23-29`
+
+```typescript
+it('should throw when attaching immediate parent as child', () => {
+  const parent = new SimpleWorkflow('Parent');
+  const child = new SimpleWorkflow('Child', parent);
+
+  expect(() => child.attachChild(parent)).toThrow(/circular|cycle|ancestor/i);
+});
+```
+
+**Key Characteristics:**
+- Setup with valid state
+- Test the invalid operation
+- Use regex to match error message keywords
+- Case-insensitive matching
+
+### Pattern 2: Specific Error Message Testing
+**File:** `src/__tests__/unit/workflow-detachChild.test.ts:22-26`
+
+```typescript
+it('should throw error when child is not attached to parent', () => {
+  const parent = new SimpleWorkflow('Parent');
+  const child = new SimpleWorkflow('Child');
+
+  expect(() => parent.detachChild(child)).toThrow(/not attached/i);
+});
+```
+
+**Key Characteristics:**
+- Minimal setup
+- Direct test of error condition
+- Specific error message assertion
+
+### Pattern 3: Constructor Parameter Testing
+**File:** `src/__tests__/unit/workflow.test.ts:20-28`
+
+```typescript
+it('should use class name as default workflow name', () => {
+  const wf = new SimpleWorkflow();
+  expect(wf.getNode().name).toBe('SimpleWorkflow');
+});
+
+it('should use custom name when provided', () => {
+  const wf = new SimpleWorkflow('CustomName');
+  expect(wf.getNode().name).toBe('CustomName');
+});
+```
+
+**Key Characteristics:**
+- Tests both default and custom behavior
+- Clear expected values
+- Uses getter method (`getNode()`)
+- Separate tests for each case
+
+### Pattern 4: Edge Case Testing
+**File:** `src/__tests__/adversarial/edge-case.test.ts:107-117`
+
+```typescript
+it('should handle empty string workflow name', async () => {
+  const workflow = new TestWorkflow('');
+  expect(workflow.node.name).toBe('');
+  await workflow.run();
+});
+```
+
+**Key Characteristics:**
+- Tests boundary condition
+- Tests both property and execution
+- Async test when execution is involved
+
+## Error Message Patterns
+
+### Descriptive Error Format
+```typescript
+// Pattern: {What} {Why} {Context} {Guidance}
+throw new Error(
+  `${operation} called outside of workflow context. ` +
+  `Agent/Prompt operations must be executed within a workflow step.`
+);
+```
+
+### Value-Including Error Format
+```typescript
+// Pattern: Include the actual invalid value in quotes
+throw new Error(`MCP server '${server.name}' is already registered`);
+```
+
+### Multi-Line Guidance Format
+```typescript
+// Pattern: Explain the constraint + provide action
+const errorMessage =
+  `Child '${child.node.name}' already has a parent '${child.parent.node.name}'. ` +
+  `A workflow can only have one parent. ` +
+  `Use detachChild() on '${child.parent.node.name}' first if you need to reparent.`;
+```
+
+## Implementation Recommendations
+
+### Validation Function Pattern
+Based on codebase patterns, workflow name validation should:
+
+```typescript
+// Location: In Workflow constructor, after config is set
+private validateName(name: unknown): string {
+  // Type check (Pattern from requireExecutionContext)
+  if (typeof name !== 'string') {
+    throw new Error(`Workflow name must be a string, received ${typeof name}`);
+  }
+
+  // Empty check (Pattern from registerServer)
+  if (name.trim().length === 0) {
+    throw new Error('Workflow name cannot be empty or whitespace only');
+  }
+
+  // Optional: Length check
+  if (name.length > 100) {
+    throw new Error('Workflow name cannot exceed 100 characters');
+  }
+
+  return name;
+}
+```
+
+### Test Pattern to Follow
+```typescript
+describe('Workflow Name Validation', () => {
+  // Test empty string
+  it('should reject empty string name', () => {
+    expect(() => new SimpleWorkflow(''))
+      .toThrow(/cannot be empty|whitespace only/i);
+  });
+
+  // Test whitespace only
+  it('should reject whitespace-only name', () => {
+    expect(() => new SimpleWorkflow('   '))
+      .toThrow(/whitespace only/i);
+  });
+
+  // Test valid name still works
+  it('should accept valid name', () => {
+    const wf = new SimpleWorkflow('ValidWorkflow');
+    expect(wf.node.name).toBe('ValidWorkflow');
+  });
+
+  // Test default class name still works
+  it('should use class name when not provided', () => {
+    const wf = new SimpleWorkflow();
+    expect(wf.node.name).toBe('SimpleWorkflow');
+  });
+});
+```
+
+## Key Gotchas
+
+1. **No custom error classes:** Codebase uses standard `Error` - follow this pattern
+2. **Error messages include values:** Always include the invalid value in quotes
+3. **Console.error before throw:** Some places log before throwing (Pattern 4)
+4. **Regex matching in tests:** Use case-insensitive regex with keywords
+5. **Separate test files:** Validation tests go in adversarial/ or unit/ directory
+
+## Files to Reference for Implementation
+
+| Purpose | File | Lines |
+|---------|------|-------|
+| Constructor location | src/core/workflow.ts | 83-108 |
+| Validation examples | src/context.ts | 42-51 |
+| Error examples | src/core/workflow.ts | 272-279 |
+| Test patterns | src/__tests__/adversarial/ | Various |
+| Existing name tests | src/__tests__/unit/workflow.test.ts | 20-28 |
+| Current empty name test | src/__tests__/adversarial/edge-case.test.ts | 107-117 |