groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/docs/research/CYCLE_DETECTION_QUICK_REF.md

@@ -0,0 +1,319 @@
+# Cycle Detection Research - Quick Reference for PRP Documents
+
+**Last Updated:** 2025-01-11
+**Source:** `/plan/docs/research/CYCLE_DETECTION_PATTERNS.md`
+
+---
+
+## Key Findings Summary
+
+### 1. Recommended Approach: WeakSet-based Detection
+
+```typescript
+function detectCycle<T extends object>(
+  node: T,
+  visited: WeakSet<T> = new WeakSet()
+): void {
+  if (visited.has(node)) {
+    throw new Error(`Cycle detected at ${getNodeId(node)}`);
+  }
+  visited.add(node);
+
+  // Process children...
+  if ('children' in node && Array.isArray((node as any).children)) {
+    for (const child of (node as any).children) {
+      detectCycle(child, visited);
+    }
+  }
+}
+```
+
+**Why WeakSet?**
+- Memory efficient (automatic garbage collection)
+- O(1) lookup/insertion
+- No manual cleanup needed
+- <5% performance overhead
+
+---
+
+### 2. Security: DoS Prevention Layers
+
+```typescript
+interface TraversalOptions {
+  maxDepth?: number;      // Prevent stack overflow (default: 1000)
+  maxNodes?: number;      // Prevent memory exhaustion (default: 10000)
+  timeoutMs?: number;     // Prevent CPU exhaustion (default: 5000ms)
+}
+
+function secureTraverse<T>(root: T, options: TraversalOptions): void {
+  const { maxDepth = 1000, maxNodes = 10000, timeoutMs = 5000 } = options;
+  const startTime = Date.now();
+  const visited = new WeakSet<object>();
+  let nodeCount = 0;
+
+  function traverse(node: any, depth: number): void {
+    // Check 1: Timeout
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Traversal timeout (${timeoutMs}ms) exceeded`);
+    }
+
+    // Check 2: Depth limit
+    if (depth > maxDepth) {
+      throw new Error(`Maximum depth (${maxDepth}) exceeded`);
+    }
+
+    // Check 3: Node count limit
+    if (nodeCount++ > maxNodes) {
+      throw new Error(`Maximum node count (${maxNodes}) exceeded`);
+    }
+
+    // Check 4: Cycle detection
+    if (visited.has(node)) {
+      throw new Error(`Circular reference detected`);
+    }
+
+    visited.add(node);
+
+    // Process children
+    if (node.children) {
+      for (const child of node.children) {
+        traverse(child, depth + 1);
+      }
+    }
+  }
+
+  traverse(root, 0);
+}
+```
+
+---
+
+### 3. Error Message Best Practices
+
+```typescript
+class CycleDetectionError extends Error {
+  constructor(
+    nodeName: string,
+    cyclePath: string[],
+    nodeType: string,
+    depth: number
+  ) {
+    super(
+      `Cycle detected in ${nodeType}:\n` +
+      `  Problem node: "${nodeName}"\n` +
+      `  Cycle path: ${cyclePath.join(' → ')}\n` +
+      `  Depth: ${depth}\n` +
+      `\n` +
+      `Common causes:\n` +
+      `  1. A node was attached as its own parent/ancestor\n` +
+      `  2. Multiple nodes form a circular reference chain\n` +
+      `  3. Shared children between different parents\n` +
+      `\n` +
+      `Suggested fixes:\n` +
+      `  - Verify parent-child relationships during attachment\n` +
+      `  - Use unique IDs for all nodes\n` +
+      `  - Add cycle detection in your attachChild() method`
+    );
+
+    this.name = 'CycleDetectionError';
+  }
+}
+```
+
+---
+
+### 4. Real-World Examples from Popular Libraries
+
+#### estree-walker (AST Traversal)
+- **URL:** https://github.com/Rich-Harris/estree-walker
+- **Pattern:** No explicit cycle detection (ASTs are guaranteed acyclic)
+- **Lesson:** If you can guarantee no cycles at creation time, skip runtime checks
+
+#### Vue.js Reactivity System
+- **URL:** https://github.com/vuejs/core
+- **Pattern:** Uses WeakMap for tracking reactive effects
+- **Lesson:** WeakMap for automatic garbage collection
+
+#### TypeScript Compiler
+- **URL:** https://github.com/microsoft/TypeScript
+- **Pattern:** Type system prevents circular references
+- **Lesson:** Use type system guarantees when possible
+
+#### JSON.stringify (V8)
+- **Pattern:** Detects circular references automatically
+- **Lesson:** Provide custom replacer for graceful handling
+
+---
+
+### 5. Performance Benchmarks (1000 nodes)
+
+| Method | Time | Memory | Recommendation |
+|--------|------|--------|----------------|
+| No detection | 1.5ms | N/A | Vulnerable |
+| **WeakSet** | 2.0ms | +5% | **Recommended** |
+| Set (IDs) | 2.8ms | +10% | Good alternative |
+| Map (paths) | 4.5ms | +25% | Debug mode only |
+
+**Conclusion:** Proper cycle detection adds <50% overhead
+
+---
+
+### 6. Integration Pattern for Workflow Classes
+
+```typescript
+export class Workflow {
+  private cycleDetector = new ProductionCycleDetector<Workflow>();
+
+  public attachChild(child: Workflow): void {
+    try {
+      // Check for cycles BEFORE attaching
+      this.cycleDetector.check(child);
+
+      // Safe to attach
+      this.children.push(child);
+      child.parent = this;
+
+      // Notify observers
+      this.emitEvent({
+        type: 'childAttached',
+        parentId: this.id,
+        child: child.node,
+      });
+    } catch (error) {
+      this.cycleDetector.reset();
+      throw new Error(`Failed to attach child: ${error.message}`);
+    }
+  }
+
+  public getRoot(): Workflow {
+    const detector = new ProductionCycleDetector<Workflow>();
+
+    function findRoot(wf: Workflow): Workflow {
+      detector.check(wf);
+      return wf.parent ? findRoot(wf.parent) : wf;
+    }
+
+    try {
+      return findRoot(this);
+    } catch (error) {
+      throw new Error(`Cycle detected: ${error.message}`);
+    }
+  }
+}
+```
+
+---
+
+### 7. Key Gotchas to Avoid
+
+1. **Shared Children:** Same child referenced by multiple parents (use true cycle detection, not just visited check)
+2. **WeakSet Can't Iterate:** Can't reconstruct full path from WeakSet alone (use parallel array tracking)
+3. **Backtracking in Non-Cyclic Graphs:** Must delete from Set when backtracking (WeakSet auto-GCs)
+4. **Primitives Can't Use WeakSet:** Use Set for string/number IDs
+5. **Async Race Conditions:** Multiple traversals can interfere (use local visited sets)
+6. **Mutation During Traversal:** Copy children arrays before iteration
+
+---
+
+### 8. Recommended Implementation Checklist
+
+- [ ] Use WeakSet for object tracking (memory efficient)
+- [ ] Add depth limiting (prevent stack overflow)
+- [ ] Add timeout protection (prevent CPU exhaustion)
+- [ ] Add node count limiting (prevent memory exhaustion)
+- [ ] Provide detailed error messages with path information
+- [ ] Reset detector state appropriately
+- [ ] Add unit tests for cycle scenarios
+- [ ] Add monitoring/metrics for production
+- [ ] Document security implications in code comments
+
+---
+
+### 9. URLs for PRP References
+
+#### Documentation
+- MDN WeakSet: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
+- MDN WeakMap: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
+- Floyd's Algorithm: https://en.wikipedia.org/wiki/Cycle_detection
+
+#### Libraries
+- estree-walker: https://github.com/Rich-Harris/estree-walker
+- TypeScript: https://github.com/microsoft/TypeScript
+- Vue.js: https://github.com/vuejs/core
+- React: https://github.com/facebook/react
+
+#### Security
+- OWASP DoS: https://owasp.org/www-community/attacks/Denial_of_Service
+- CWE-835: https://cwe.mitre.org/data/definitions/835.html
+
+#### Tools
+- flatted: https://github.com/WebReflection/flatted
+- json-stringify-safe: https://github.com/moll/json-stringify-safe
+
+---
+
+### 10. Copy-Paste Ready Implementation
+
+```typescript
+/**
+ * Production cycle detector
+ * Usage: new ProductionCycleDetector().check(node)
+ */
+export class ProductionCycleDetector<T extends object> {
+  private visited = new WeakSet<T>();
+  private path: T[] = [];
+  private readonly maxDepth: number;
+  private readonly timeout: number;
+  private startTime: number;
+
+  constructor(options: { maxDepth?: number; timeoutMs?: number } = {}) {
+    this.maxDepth = options.maxDepth ?? 1000;
+    this.timeout = options.timeoutMs ?? 5000;
+    this.startTime = Date.now();
+  }
+
+  check(node: T): void {
+    // Timeout check
+    if (Date.now() - this.startTime > this.timeout) {
+      throw new Error(`Traversal timeout (${this.timeout}ms) exceeded`);
+    }
+
+    // Depth check
+    if (this.path.length > this.maxDepth) {
+      throw new Error(`Maximum depth (${this.maxDepth}) exceeded`);
+    }
+
+    // Cycle check
+    if (this.visited.has(node)) {
+      const pathInfo = this.path.map(n =>
+        (n as any).id || (n as any).name || 'unknown'
+      ).join(' -> ');
+
+      throw new Error(
+        `Cycle detected.\n` +
+        `Node type: ${(node as any).constructor.name}\n` +
+        `Path: ${pathInfo}\n` +
+        `Depth: ${this.path.length}`
+      );
+    }
+
+    this.visited.add(node);
+    this.path.push(node);
+  }
+
+  leave(node: T): void {
+    const index = this.path.lastIndexOf(node);
+    if (index !== -1) this.path.splice(index, 1);
+  }
+
+  reset(): void {
+    this.visited = new WeakSet();
+    this.path = [];
+    this.startTime = Date.now();
+  }
+}
+```
+
+---
+
+**For Full Details:** See `/plan/docs/research/CYCLE_DETECTION_PATTERNS.md`

package/plan/001_d3bb02af4886/docs/research/P1M1T2S1/codebase-context.md

@@ -0,0 +1,115 @@
+# Codebase Context Research: P1.M1.T2.S1
+
+## Project Structure
+
+```
+/home/dustin/projects/groundswell/
+├── src/
+│   ├── core/
+│   │   └── workflow.ts          # Main Workflow class (349 lines)
+│   ├── types/
+│   │   ├── workflow.ts          # Workflow type definitions
+│   │   ├── events.ts            # Event type definitions
+│   │   └── observer.ts          # Observer interface
+│   └── __tests__/
+│       ├── adversarial/
+│       │   └── parent-validation.test.ts  # Reference test pattern
+│       ├── unit/
+│       │   └── workflow.test.ts
+│       └── integration/
+├── plan/
+│   └── bugfix/
+│       ├── P1M1T1S1/            # Completed parent validation
+│       │   ├── research/        # Research docs from S1
+│       │   └── PRP.md
+│       └── P1M1T2S1/            # Current work item
+│           └── research/
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+## Test Framework
+
+- **Framework**: Vitest
+- **Config**: `vitest.config.ts`
+- **Test command**: `npm test` (runs `vitest run`)
+- **Watch mode**: `npm run test:watch`
+- **Current status**: 242 tests passing
+
+## TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  }
+}
+```
+
+## Build/Test Commands
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Type check
+npm run lint  # Runs tsc --noEmit
+
+# Build
+npm run build
+```
+
+## Task Status (from bug_fix_tasks.json)
+
+**P1.M1.T1 - Parent Validation - COMPLETED**
+- Parent validation implemented in attachChild()
+- Tests passing
+
+**P1.M1.T2 - Circular Reference Detection - IN PROGRESS**
+- S1: Write failing test (CURRENT TASK)
+- S2: Implement isDescendantOf() helper method
+- S3: Integrate circular reference check into attachChild()
+- S4: Verify no regressions
+
+## Related Documentation
+
+- **Implementation Patterns**: `/plan/docs/bugfix-architecture/implementation_patterns.md`
+- **Bug Analysis**: `/plan/docs/bugfix-architecture/bug_analysis.md`
+- **Cycle Detection Research**: `/plan/docs/research/CYCLE_DETECTION_PATTERNS.md`
+
+## Dependencies
+
+```json
+{
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.1",
+    "lru-cache": "^10.4.3",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.2.0",
+    "tsx": "^4.21.0",
+    "vitest": "^1.0.0"
+  }
+}
+```
+
+## Import Patterns
+
+```typescript
+// For tests
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Workflow } from '../../index.js';
+
+// For implementation
+import { Workflow } from './workflow.js';
+import type { WorkflowEvent, WorkflowNode } from '../types/index.js';
+```

package/plan/001_d3bb02af4886/docs/research/P1M1T2S1/cycle-detection-algorithms.md

@@ -0,0 +1,134 @@
+# Cycle Detection Research: P1.M1.T2.S1
+
+## isDescendantOf() Pattern
+
+The key method needed for circular reference detection is `isDescendantOf()`. This checks if a given workflow is an ancestor of the current workflow by traversing the parent chain.
+
+### Recommended Implementation Pattern
+
+```typescript
+/**
+ * Check if this workflow is a descendant of another workflow
+ * Used to prevent circular references in attachChild()
+ */
+private isDescendantOf(ancestor: Workflow): boolean {
+  const visited = new Set<Workflow>();
+  let current: Workflow | null = this.parent;
+
+  while (current !== null) {
+    // Cycle detection during traversal itself (defensive)
+    if (visited.has(current)) {
+      throw new Error('Circular reference detected in tree structure');
+    }
+    visited.add(current);
+
+    if (current === ancestor) {
+      return true;
+    }
+    current = current.parent;
+  }
+
+  return false;
+}
+```
+
+## Usage in attachChild()
+
+```typescript
+public attachChild(child: Workflow): void {
+  // ... existing validations ...
+
+  // Validation: Prevent circular references
+  if (this.isDescendantOf(child)) {
+    throw new Error(
+      `Cannot attach '${child.node.name}' to '${this.node.name}': ` +
+      `would create circular reference`
+    );
+  }
+
+  // ... rest of method ...
+}
+```
+
+## Test Scenarios to Cover
+
+### Scenario 1: Immediate Circular Reference
+```typescript
+const parent = new Workflow('Parent');
+const child = new Workflow('Child', parent);
+
+// This should throw - child is trying to attach its parent
+expect(() => child.attachChild(parent)).toThrow(/circular|cycle|ancestor/);
+```
+
+### Scenario 2: Ancestor Circular Reference (Multi-level)
+```typescript
+const root = new Workflow('Root');
+const child1 = new Workflow('Child1', root);
+const child2 = new Workflow('Child2', child1);
+
+// This should throw - root is an ancestor of child2
+expect(() => child2.attachChild(root)).toThrow(/circular|cycle|ancestor/);
+```
+
+## Error Message Convention
+
+From implementation_patterns.md:
+- Error should contain 'circular' OR 'cycle' OR 'ancestor'
+- Pattern from research: `toThrow(/circular|cycle|ancestor/)`
+
+## Performance Considerations
+
+- **Time Complexity**: O(h) where h is the height of the tree
+- **Space Complexity**: O(h) for the visited Set
+- **DoS Protection**: Consider max depth limit (currently not implemented)
+
+## Related Code Patterns
+
+### Existing getRoot() Pattern (similar traversal)
+```typescript
+// From workflow.ts - shows similar parent chain traversal pattern
+private getRoot(): Workflow {
+  const visited = new Set<Workflow>();
+  let current: Workflow | null = this;
+
+  while (current) {
+    if (visited.has(current)) {
+      throw new Error('Circular parent-child relationship detected');
+    }
+    visited.add(current);
+    current = current.parent;
+  }
+
+  return Array.from(visited).pop()!;
+}
+```
+
+### Event Tree Ancestor Pattern
+```typescript
+// From src/core/event-tree.ts - similar ancestor tracking
+public getAncestors(id: string): EventNode[] {
+  const ancestors: EventNode[] = [];
+  const node = this.nodeIndex.get(id);
+
+  if (!node || !node.parentId) {
+    return ancestors;
+  }
+
+  let currentId = node.parentId;
+  while (currentId) {
+    const parent = this.nodeIndex.get(currentId);
+    if (!parent) break;
+    ancestors.push(parent);
+    currentId = parent.parentId ?? '';
+  }
+
+  return ancestors;
+}
+```
+
+## Key Sources
+
+- **Research Document**: `/home/dustin/projects/groundswell/plan/docs/research/CYCLE_DETECTION_PATTERNS.md`
+- **Quick Reference**: `/home/dustin/projects/groundswell/plan/docs/research/CYCLE_DETECTION_QUICK_REF.md`
+- **Implementation Patterns**: `/home/dustin/projects/groundswell/plan/docs/bugfix-architecture/implementation_patterns.md`