groundswell 0.0.2 → 1.0.0

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

@@ -1,265 +0,0 @@
-# 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

@@ -1,273 +0,0 @@
-# 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 |