groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/docs/PRP_P1M3T1S3.md

@@ -1,499 +0,0 @@
-# PRP: Write Complex Circular Reference Tests
-
----
-
-## Goal
-
-**Feature Goal**: Create a comprehensive test file for circular reference detection at various depths (immediate child, grandchild, great-grandchild) to validate that `isDescendantOf()` correctly prevents cycles through the entire ancestor chain.
-
-**Deliverable**: New test file `src/__tests__/adversarial/complex-circular-reference.test.ts` with three test cases covering different cycle depths.
-
-**Success Definition**:
-- All three test cases pass when run with `npm run test`
-- Each test validates that `attachChild()` throws an error containing 'circular', 'cycle', or 'ancestor' (case-insensitive)
-- Tests follow the existing adversarial test patterns (AAA structure, console mocking, TDD documentation)
-- Tests are properly documented with inline comments explaining the cycle detection mechanism
-
-## User Persona (if applicable)
-
-**Target User**: Developer implementing the Workflow class tree integrity validation.
-
-**Use Case**: Validating that circular reference detection works correctly across various ancestor depths in the workflow tree.
-
-**User Journey**:
-1. Developer writes code to attach a workflow as a child
-2. If the child is an ancestor (at any depth), `attachChild()` must throw an error
-3. These tests verify the error is thrown for immediate parent (depth 1), grandparent (depth 2), and great-grandparent (depth 3)
-
-**Pain Points Addressed**:
-- Detects subtle bugs where cycle detection only works for immediate parent but not deeper ancestors
-- Prevents infinite loops in tree traversal methods like `getRoot()` and `getRootObservers()`
-- Validates defensive programming against manual parent mutation
-
-## Why
-
-- **Security**: Circular references cause infinite loops in tree traversal, leading to DoS vulnerabilities
-- **Data Integrity**: Cycles break the tree invariant, causing incorrect behavior in observer propagation and state management
-- **Bug Prevention**: Existing tests in `circular-reference.test.ts` only test depth 1 (immediate parent) and depth 2 (ancestor). This adds depth 3 coverage
-- **Pattern Compliance**: Fulfills Pattern 8 from `plan/bugfix/architecture/implementation_patterns.md` which requires testing cycles at various depths
-
-## What
-
-Create a new test file `src/__tests__/adversarial/complex-circular-reference.test.ts` with three test cases:
-
-1. **Immediate Circular Reference**: `child.attachChild(parent)` - depth 1 cycle
-2. **Two-Level Circular Reference**: `child2.attachChild(root)` where root → child1 → child2 - depth 2 cycle
-3. **Three-Level Circular Reference**: `child3.attachChild(root)` where root → child1 → child2 → child3 - depth 3 cycle
-
-Each test must:
-- Create a 4-level hierarchy (root, child1, child2, child3)
-- Attempt to create a circular reference by attaching an ancestor as a child
-- Assert that an error is thrown with message matching `/circular|cycle|ancestor/i`
-
-### Success Criteria
-
-- [ ] Test file created at `src/__tests__/adversarial/complex-circular-reference.test.ts`
-- [ ] All three test cases for different cycle depths are implemented
-- [ ] All tests pass with `npm run test`
-- [ ] Tests follow existing patterns from `circular-reference.test.ts` and `deep-hierarchy-stress.test.ts`
-- [ ] Proper documentation comments explain each test scenario
-
-## All Needed Context
-
-### Context Completeness Check
-
-_Before writing this PRP, validate: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_
-
-**YES** - This PRP provides:
-- Exact file paths and code patterns to follow
-- Complete `isDescendantOf()` implementation for reference
-- Existing test file examples with identical patterns
-- Vitest configuration and test commands
-- Console mocking pattern from existing tests
-
-### Documentation & References
-
-```yaml
-# MUST READ - Critical implementation files
-
-- file: /home/dustin/projects/groundswell/src/core/workflow.ts
-  why: Contains isDescendantOf() implementation and attachChild() circular reference check
-  pattern: Lines 150-168 (isDescendantOf method), lines 232-238 (circular reference check in attachChild)
-  gotcha: isDescendantOf() starts from this.parent, not this - prevents self-reference false positive
-
-- file: /home/dustin/projects/groundswell/src/__tests__/adversarial/circular-reference.test.ts
-  why: Pattern template for circular reference tests - same AAA structure, console mocking, error assertions
-  pattern: Lines 20-26 (SimpleWorkflow class), 33-45 (console mocking pattern), 58-71 (immediate cycle test), 84-100 (ancestor cycle test)
-  gotcha: Must use `vi.restoreAllMocks()` in afterEach to prevent test pollution
-
-- file: /home/dustin/projects/groundswell/src/__tests__/adversarial/deep-hierarchy-stress.test.ts
-  why: Pattern for building multi-level hierarchies and testing protected/private methods
-  pattern: Lines 20-26 (SimpleWorkflow class), 94-109 (building deep hierarchy with loop), 104 (casting to any for protected method access)
-  gotcha: getRoot() and isDescendantOf() are not public - cast to `any` for testing
-
-- file: /home/dustin/projects/groundswell/plan/docs/bugfix-architecture/implementation_patterns.md
-  why: Pattern 8 defines the requirement for testing cycles at various depths
-  section: Pattern 8 - Adversarial Testing (see complex circular reference test example)
-  gotcha: Tests should cover immediate child, grandchild, and great-grandchild scenarios
-
-- file: /home/dustin/projects/groundswell/vitest.config.ts
-  why: Confirms test file location pattern and vitest configuration
-  pattern: Line 5 - test glob pattern is `src/__tests__/**/*.test.ts`
-  gotcha: All test files must end in `.test.ts` to be discovered by vitest
-
-- url: https://vitest.dev/api/expect.html#tothrow
-  why: Official vitest documentation for toThrow() assertion patterns
-  critical: Supports regex patterns like `/circular|cycle|ancestor/i` for flexible error matching
-```
-
-### Current Codebase tree (relevant sections)
-
-```bash
-src/
-├── core/
-│   └── workflow.ts                    # Workflow class with isDescendantOf() and attachChild()
-└── __tests__/
-    └── adversarial/
-        ├── circular-reference.test.ts      # Existing basic cycle tests (depth 1, 2)
-        ├── deep-hierarchy-stress.test.ts   # Deep hierarchy tests (1000+ levels)
-        └── complex-circular-reference.test.ts  # TO BE CREATED - multi-depth cycle tests
-```
-
-### Desired Codebase tree with files to be added
-
-```bash
-src/
-├── core/
-│   └── workflow.ts                    # NO CHANGE - isDescendantOf() already implemented
-└── __tests__/
-    └── adversarial/
-        ├── circular-reference.test.ts      # EXISTING - basic cycle tests
-        ├── deep-hierarchy-stress.test.ts   # EXISTING - deep hierarchy tests
-        └── complex-circular-reference.test.ts  # NEW FILE - depth 1, 2, 3 cycle tests
-            # Responsibility: Validate isDescendantOf() detects cycles at various ancestor depths
-```
-
-### Known Gotchas of our codebase & Library Quirks
-
-```typescript
-// CRITICAL: Constructor auto-attaches child when parent is provided
-// Pattern: workflow.ts:113-116
-const child = new Workflow('Child', parent);
-// This internally calls parent.attachChild(child) automatically
-
-// CRITICAL: isDescendantOf() starts from this.parent, not this
-// Implementation: workflow.ts:152
-let current: Workflow | null = this.parent;  // NOT this!
-// This prevents self-reference false positive: root.isDescendantOf(root) === false
-
-// CRITICAL: isDescendantOf() and getRoot() are private/protected
-// Must cast to `any` in tests to access them:
-(root as any).isDescendantOf(child);
-(deepest as any).getRoot();
-
-// CRITICAL: Always use vi.restoreAllMocks() in afterEach
-// Pattern: circular-reference.test.ts:43-45
-afterEach(() => {
-  vi.restoreAllMocks();  // Prevents test pollution
-});
-
-// CRITICAL: Error message regex must be case-insensitive
-// attachChild throws: "it is an ancestor of" (lowercase 'ancestor')
-// Use: /circular|cycle|ancestor/i (note the 'i' flag for case-insensitive)
-
-// CRITICAL: Workflow constructor auto-attaches - DON'T manually call attachChild
-// WRONG: const child = new Workflow('Child'); parent.attachChild(child);
-// RIGHT: const child = new Workflow('Child', parent);  // Auto-attaches
-
-// CRITICAL: When building hierarchies, track the last child
-// Pattern: deep-hierarchy-stress.test.ts:94-101
-let current: any = root;
-for (let i = 0; i < DEPTH; i++) {
-  current = new SimpleWorkflow(`Child-${i}`, current);
-}
-// After loop, `current` is the deepest child
-```
-
-## Implementation Blueprint
-
-### Data models and structure
-
-No data models needed - tests only use existing Workflow class.
-
-```typescript
-// Test helper class (same pattern used in all adversarial tests)
-class SimpleWorkflow extends Workflow {
-  async run(): Promise<string> {
-    this.setStatus('running');
-    this.setStatus('completed');
-    return 'done';
-  }
-}
-```
-
-### Implementation Tasks (ordered by dependencies)
-
-```yaml
-Task 1: CREATE src/__tests__/adversarial/complex-circular-reference.test.ts
-  - IMPLEMENT: Three test cases for cycle detection at depths 1, 2, 3
-  - FOLLOW pattern: src/__tests__/adversarial/circular-reference.test.ts (AAA structure, console mocking)
-  - NAMING: describe() = "Adversarial: Complex Circular Reference Detection"
-  - PLACEMENT: src/__tests__/adversarial/ directory
-
-Task 2: IMPLEMENT Test 1 - Immediate Circular Reference (depth 1)
-  - CREATE: 2-level hierarchy (root, child1)
-  - ATTEMPT: child1.attachChild(root)
-  - ASSERT: Error thrown with /circular|cycle|ancestor/i
-  - FOLLOW pattern: circular-reference.test.ts:58-71
-  - DOCUMENT: "immediate cycle" in test description
-
-Task 3: IMPLEMENT Test 2 - Two-Level Circular Reference (depth 2)
-  - CREATE: 3-level hierarchy (root, child1, child2)
-  - ATTEMPT: child2.attachChild(root)
-  - ASSERT: Error thrown with /circular|cycle|ancestor/i
-  - FOLLOW pattern: circular-reference.test.ts:84-100 (ancestor test)
-  - DOCUMENT: "2-level cycle" in test description
-
-Task 4: IMPLEMENT Test 3 - Three-Level Circular Reference (depth 3)
-  - CREATE: 4-level hierarchy (root, child1, child2, child3)
-  - ATTEMPT: child3.attachChild(root)
-  - ASSERT: Error thrown with /circular|cycle|ancestor/i
-  - FOLLOW pattern: deep-hierarchy-stress.test.ts:94-109 (hierarchy building)
-  - DOCUMENT: "3-level cycle" in test description - NEW coverage not in existing tests
-
-Task 5: VERIFY all tests pass
-  - RUN: npm run test -- complex-circular-reference
-  - EXPECT: All 3 tests pass
-  - VALIDATE: Error messages are informative
-```
-
-### Implementation Patterns & Key Details
-
-```typescript
-// ============================================
-// PATTERN 1: File Header Documentation
-// ============================================
-/**
- * Complex Circular Reference Tests
- *
- * These tests validate that isDescendantOf() correctly detects circular
- * references at various depths in the workflow tree.
- *
- * Test Cases:
- * 1. Immediate circular reference (depth 1): child.attachChild(parent)
- * 2. Two-level circular reference (depth 2): grandchild.attachChild(root)
- * 3. Three-level circular reference (depth 3): great-grandchild.attachChild(root)
- *
- * Pattern from: plan/docs/bugfix-architecture/implementation_patterns.md Pattern 8
- * Related: plan/bugfix/P1M3T1S3/PRP.md
- */
-
-// ============================================
-// PATTERN 2: Test Helper Class
-// ============================================
-class SimpleWorkflow extends Workflow {
-  async run(): Promise<string> {
-    this.setStatus('running');
-    this.setStatus('completed');
-    return 'done';
-  }
-}
-// FOLLOW: circular-reference.test.ts:20-26
-
-// ============================================
-// PATTERN 3: Console Mocking Setup
-// ============================================
-describe('Adversarial: Complex Circular Reference Detection', () => {
-  beforeEach(() => {
-    vi.spyOn(console, 'log').mockImplementation(() => {});
-    vi.spyOn(console, 'error').mockImplementation(() => {});
-    vi.spyOn(console, 'warn').mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();  // CRITICAL: Always restore mocks
-  });
-  // FOLLOW: circular-reference.test.ts:33-45
-});
-
-// ============================================
-// PATTERN 4: Test Case Structure (AAA)
-// ============================================
-it('should throw when attaching immediate parent as child (depth 1)', () => {
-  // ========== ARRANGE ==========
-  const parent = new SimpleWorkflow('Parent');
-  const child = new SimpleWorkflow('Child', parent);
-
-  // Verify initial state
-  expect(child.parent).toBe(parent);
-  expect(parent.children).toContain(child);
-
-  // ========== ACT & ASSERT ==========
-  expect(() => child.attachChild(parent)).toThrow(/circular|cycle|ancestor/i);
-});
-
-// ============================================
-// PATTERN 5: Multi-Level Hierarchy Building
-// ============================================
-// For depth 3 test (4 levels: root, child1, child2, child3)
-const root = new SimpleWorkflow('Root');
-const child1 = new SimpleWorkflow('Child1', root);  // root -> child1
-const child2 = new SimpleWorkflow('Child2', child1); // root -> child1 -> child2
-const child3 = new SimpleWorkflow('Child3', child2); // root -> child1 -> child2 -> child3
-
-// Verify hierarchy
-expect(child3.parent).toBe(child2);
-expect(child2.parent).toBe(child1);
-expect(child1.parent).toBe(root);
-
-// Attempt cycle: child3.attachChild(root)
-expect(() => child3.attachChild(root)).toThrow(/circular|cycle|ancestor/i);
-
-// FOLLOW: deep-hierarchy-stress.test.ts:94-109
-
-// ============================================
-// PATTERN 6: Error Message Validation
-// ============================================
-// The attachChild() method throws specific error messages:
-// workflow.ts:234-235: "it is an ancestor of '...'. This would create a circular reference."
-//
-// Use regex pattern matching for flexibility:
-expect(() => child.attachChild(parent)).toThrow(/circular|cycle|ancestor/i);
-// The 'i' flag makes it case-insensitive
-
-// GOTCHA: Error message uses "ancestor" (lowercase), not "Ancestor"
-// Gotcha source: workflow.ts:234
-
-// ============================================
-// PATTERN 7: Constructor Auto-Attachment
-// ============================================
-// CRITICAL: When parent is passed to constructor, attachChild() is called automatically
-// Implementation: workflow.ts:114-116
-if (this.parent) {
-  this.parent.attachChild(this);
-}
-
-// CORRECT USAGE:
-const child = new SimpleWorkflow('Child', parent);  // Auto-attaches
-
-// WRONG USAGE (don't do this):
-const child = new SimpleWorkflow('Child');
-parent.attachChild(child);  // Redundant, constructor already did it
-```
-
-### Integration Points
-
-```yaml
-TEST_FRAMEWORK:
-  - runner: vitest (configured in vitest.config.ts)
-  - glob: src/__tests__/**/*.test.ts
-  - command: npm run test -- [filename]
-
-IMPORTS:
-  - from: 'vitest'
-    imports: describe, it, expect, beforeEach, afterEach, vi
-  - from: '../../index.js'
-    import: Workflow class
-
-NO_CHANGES_NEEDED:
-  - workflow.ts: isDescendantOf() already implemented at lines 150-168
-  - workflow.ts: attachChild() circular reference check already at lines 232-238
-```
-
-## Validation Loop
-
-### Level 1: Syntax & Style (Immediate Feedback)
-
-```bash
-# Run after file creation - fix before proceeding
-npm run test -- complex-circular-reference  # Run just the new test file
-
-# Expected: Tests should PASS (isDescendantOf is already implemented)
-# If tests FAIL, read output and fix test implementation
-
-# Full test suite validation (ensure no regressions)
-npm run test
-
-# Expected: All tests pass
-```
-
-### Level 2: Unit Tests (Component Validation)
-
-```bash
-# Run specific test file
-npm run test -- complex-circular-reference
-
-# Expected output:
-# ✓ src/__tests__/adversarial/complex-circular-reference.test.ts (3)
-#   ✓ Adversarial: Complex Circular Reference Detection (3)
-#     ✓ should throw when attaching immediate parent as child (depth 1)
-#     ✓ should throw when attaching grandparent as child (depth 2)
-#     ✓ should throw when attaching great-grandparent as child (depth 3)
-
-# Full adversarial test suite
-npm run test -- adversarial
-
-# Expected: All adversarial tests pass
-```
-
-### Level 3: Integration Testing (System Validation)
-
-```bash
-# Verify test file is discovered by vitest glob pattern
-npm run test -- --reporter=verbose 2>&1 | grep complex-circular-reference
-
-# Expected: Test file is found and executed
-
-# Verify no regressions in existing circular reference tests
-npm run test -- circular-reference
-
-# Expected: Existing tests still pass
-```
-
-### Level 4: Creative & Domain-Specific Validation
-
-```bash
-# Vitest coverage (if coverage is configured)
-npm run test -- --coverage
-
-# Expected: New lines covered in isDescendantOf() method
-
-# Performance test - ensure tests run quickly
-time npm run test -- complex-circular-reference
-
-# Expected: Tests complete in < 1 second (simple operations)
-
-# Validate error messages are informative
-npm run test -- complex-circular-reference 2>&1 | grep -i "ancestor\|circular"
-
-# Expected: Error messages contain clear descriptions
-```
-
-## Final Validation Checklist
-
-### Technical Validation
-
-- [ ] Test file created at `src/__tests__/adversarial/complex-circular-reference.test.ts`
-- [ ] All three test cases pass: `npm run test -- complex-circular-reference`
-- [ ] No regressions: `npm run test` passes completely
-- [ ] Console properly mocked (check for no console output in test results)
-- [ ] Error assertions use correct regex pattern: `/circular|cycle|ancestor/i`
-
-### Feature Validation
-
-- [ ] Test 1 validates depth 1 cycle (immediate parent)
-- [ ] Test 2 validates depth 2 cycle (grandparent)
-- [ ] Test 3 validates depth 3 cycle (great-grandparent)
-- [ ] All tests properly verify initial hierarchy state before attempting cycle
-- [ ] Tests follow AAA pattern (Arrange, Act, Assert)
-
-### Code Quality Validation
-
-- [ ] File header documentation includes Pattern 8 reference
-- [ ] Test descriptions clearly indicate cycle depth
-- [ ] Inline comments explain the cycle being tested
-- [ ] Console mocking follows existing pattern with vi.restoreAllMocks()
-- [ ] SimpleWorkflow class included (no external dependencies)
-
-### Documentation & Deployment
-
-- [ ] PRP path saved at plan/bugfix/P1M3T1S3/PRP.md
-- [ ] Test file follows naming convention: `*-circular-reference.test.ts`
-- [ ] Test file located in correct directory: `src/__tests__/adversarial/`
-- [ ] Related test files referenced in documentation
-
----
-
-## Anti-Patterns to Avoid
-
-- **Don't** manually call `attachChild()` when constructor already does it - just pass parent to constructor
-- **Don't** forget `vi.restoreAllMocks()` in afterEach - causes test pollution
-- **Don't** use exact string match for error assertions - use regex `/circular|cycle|ancestor/i`
-- **Don't** forget to verify initial state before testing the cycle
-- **Don't** create tests that are too similar to existing `circular-reference.test.ts` - this file adds depth 3 coverage
-- **Don't** skip the `i` flag on regex - error messages use specific casing
-- **Don't** use recursion to build hierarchies in tests - use iteration (avoids test-side stack overflow)
-- **Don't** test `isDescendantOf()` directly without casting to `any` - it's private
-
-## Test Specification Summary
-
-| Test Name | Hierarchy Depth | Cycle Attempt | Expected Error |
-|-----------|----------------|---------------|----------------|
-| Immediate Circular Reference (depth 1) | 2 (root, child1) | child1.attachChild(root) | /circular\|cycle\|ancestor/i |
-| Two-Level Circular Reference (depth 2) | 3 (root, child1, child2) | child2.attachChild(root) | /circular\|cycle\|ancestor/i |
-| Three-Level Circular Reference (depth 3) | 4 (root, child1, child2, child3) | child3.attachChild(root) | /circular\|cycle\|ancestor/i |
-
-## Success Metrics
-
-**Confidence Score**: 10/10 for one-pass implementation success
-
-**Validation**: The PRP provides complete context including:
-- Exact file paths and line numbers for all references
-- Complete code examples for all patterns
-- Existing test files with identical patterns to follow
-- isDescendantOf() implementation for reference
-- Vitest configuration and test commands
-- Console mocking pattern with gotchas documented
-- Constructor auto-attachment behavior explained
-
-An AI agent unfamiliar with this codebase can implement this successfully using only the PRP content and codebase access.