groundswell 0.0.2 → 0.0.3

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

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

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

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