groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/docs/research/P1M3T1S4/QUICK_REFERENCE.md

@@ -1,339 +0,0 @@
-# Quick Reference: Bidirectional Tree Consistency Testing
-
-**For immediate use in writing tests**
-
----
-
-## The Golden Rule
-
-> **Every tree operation MUST update BOTH trees (Workflow + WorkflowNode) atomically**
-
-If you attach a child to a parent, you must update:
-1. `child.parent` (workflow tree)
-2. `parent.children` (workflow tree)
-3. `child.node.parent` (node tree)
-4. `parent.node.children` (node tree)
-
-All four must happen, or trees become inconsistent.
-
----
-
-## Essential Helper Functions
-
-### verifyBidirectionalLink(parent, child)
-Use after every `attachChild()` and after reparenting
-
-```typescript
-import { verifyBidirectionalLink } from '../helpers/tree-verification';
-
-// After attaching
-parent.attachChild(child);
-verifyBidirectionalLink(parent, child); // ✅ Checks both trees
-```
-
-### verifyTreeMirror(root)
-Use to ensure 1:1 correspondence between trees
-
-```typescript
-import { verifyTreeMirror } from '../helpers/tree-verification';
-
-// After tree mutations
-parent.detachChild(child);
-newParent.attachChild(child);
-verifyTreeMirror(newParent); // ✅ Validates entire tree
-```
-
-### validateTreeConsistency(root)
-Returns array of inconsistency descriptions
-
-```typescript
-import { validateTreeConsistency } from '../helpers/tree-verification';
-
-const errors = validateTreeConsistency(root);
-expect(errors).toEqual([]); // ✅ Empty = valid tree
-```
-
----
-
-## Test Template (Copy-Paste)
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { Workflow } from '../../index.js';
-import { verifyBidirectionalLink, verifyTreeMirror, validateTreeConsistency } from '../helpers/tree-verification';
-
-class TestWorkflow extends Workflow {
-  async run(): Promise<string> {
-    return 'done';
-  }
-}
-
-describe('Tree Consistency', () => {
-  it('should maintain consistency after [OPERATION]', () => {
-    // ARRANGE
-    const parent = new TestWorkflow('Parent');
-    const child = new TestWorkflow('Child');
-
-    // ACT
-    parent.attachChild(child);
-
-    // ASSERT - Always check both trees!
-    verifyBidirectionalLink(parent, child);
-    verifyTreeMirror(parent);
-    expect(validateTreeConsistency(parent)).toEqual([]);
-  });
-});
-```
-
----
-
-## Critical Invariants
-
-### 1. Tree Mirror Invariant
-**If A is B's parent in workflow tree, A must be B's parent in node tree**
-
-```typescript
-// ✅ CORRECT
-expect(child.parent).toBe(parent);           // Workflow tree
-expect(child.node.parent).toBe(parent.node); // Node tree (MUST match)
-
-// ❌ WRONG - Only checks one tree
-expect(child.parent).toBe(parent);
-```
-
-### 2. Bidirectional Link Invariant
-**If A is B's parent, B must be in A's children array (in BOTH trees)**
-
-```typescript
-// ✅ CORRECT - Checks both directions
-expect(child.parent).toBe(parent);
-expect(parent.children).toContain(child);
-expect(child.node.parent).toBe(parent.node);
-expect(parent.node.children).toContain(child.node);
-
-// ❌ WRONG - Only checks forward direction
-expect(parent.children).toContain(child);
-```
-
-### 3. No Orphaned Nodes Invariant
-**Every non-root node must have exactly one parent who claims it**
-
-```typescript
-// ✅ CORRECT
-// child has parent
-expect(child.parent).toBe(parent);
-// parent knows about child
-expect(parent.children).toContain(child);
-// No other parent claims this child
-const otherClaimants = allNodes.filter(n => n !== parent && n.children.includes(child));
-expect(otherClaimants).toEqual([]);
-```
-
----
-
-## Common Test Scenarios
-
-### Scenario 1: Test attachChild()
-```typescript
-it('should maintain consistency after attach', () => {
-  const parent = new TestWorkflow('Parent');
-  const child = new TestWorkflow('Child');
-
-  parent.attachChild(child);
-
-  // Verify bidirectional links
-  verifyBidirectionalLink(parent, child);
-
-  // Verify tree mirror
-  verifyTreeMirror(parent);
-
-  // Verify no inconsistencies
-  expect(validateTreeConsistency(parent)).toEqual([]);
-});
-```
-
-### Scenario 2: Test detachChild()
-```typescript
-it('should maintain consistency after detach', () => {
-  const parent = new TestWorkflow('Parent');
-  const child = new TestWorkflow('Child', parent);
-
-  parent.detachChild(child);
-
-  // Verify complete detachment
-  expect(child.parent).toBeNull();
-  expect(parent.children).not.toContain(child);
-  expect(child.node.parent).toBeNull();
-  expect(parent.node.children).not.toContain(child.node);
-
-  verifyTreeMirror(parent);
-});
-```
-
-### Scenario 3: Test Reparenting
-```typescript
-it('should maintain consistency during reparenting', () => {
-  const parent1 = new TestWorkflow('Parent1');
-  const parent2 = new TestWorkflow('Parent2');
-  const child = new TestWorkflow('Child', parent1);
-
-  // Verify initial state
-  verifyBidirectionalLink(parent1, child);
-
-  // Reparent
-  parent1.detachChild(child);
-  parent2.attachChild(child);
-
-  // Verify new state
-  verifyBidirectionalLink(parent2, child);
-
-  // Verify old parent no longer has child
-  expect(parent1.children).not.toContain(child);
-  expect(parent1.node.children).not.toContain(child.node);
-
-  // Verify both trees are valid
-  verifyTreeMirror(parent1);
-  verifyTreeMirror(parent2);
-});
-```
-
-### Scenario 4: Test Error Handling
-```typescript
-it('should not corrupt state on duplicate attach', () => {
-  const parent = new TestWorkflow('Parent');
-  const child = new TestWorkflow('Child', parent);
-
-  // Should throw
-  expect(() => parent.attachChild(child)).toThrow();
-
-  // Verify state unchanged
-  verifyBidirectionalLink(parent, child);
-  verifyTreeMirror(parent);
-});
-```
-
----
-
-## Anti-Patterns to Avoid
-
-### ❌ Don't check only workflow tree
-```typescript
-// BAD: Only checks workflow tree
-expect(child.parent).toBe(parent);
-expect(parent.children).toContain(child);
-// ❌ Missing node tree checks!
-```
-
-### ❌ Don't check only one direction
-```typescript
-// BAD: Only checks parent→child
-expect(parent.children).toContain(child);
-// ❌ Missing child→parent check!
-```
-
-### ❌ Don't forget to verify both trees after errors
-```typescript
-// BAD: Error case not validated
-expect(() => parent2.attachChild(child)).toThrow();
-// ❌ Should verify no corruption occurred!
-```
-
-### ❌ Don't manually mutate tree properties
-```typescript
-// BAD: Bypasses attachChild validation
-(child as any).parent = newParent;
-// ❌ Creates inconsistency!
-```
-
----
-
-## Quick Checklist
-
-When writing tree operation tests, ensure you:
-
-- [ ] Test both workflow tree AND node tree
-- [ ] Test parent→child AND child→parent directions
-- [ ] Use helper functions (verifyBidirectionalLink, verifyTreeMirror)
-- [ ] Run validateTreeConsistency to check for hidden issues
-- [ ] Test error cases don't corrupt state
-- [ ] Verify state after attach, detach, and reparenting
-- [ ] Test with multiple children
-- [ ] Test with deep hierarchies
-- [ ] Test edge cases (null parent, duplicate attach, circular refs)
-
----
-
-## Common Patterns
-
-### Pattern: Verify After Every Operation
-```typescript
-operation();
-verifyTreeMirror(root);
-expect(validateTreeConsistency(root)).toEqual([]);
-```
-
-### Pattern: Test Error Cases Don't Corrupt
-```typescript
-expect(() => invalidOperation()).toThrow();
-verifyTreeMirror(root); // State still valid
-```
-
-### Pattern: Test Both Trees Explicitly
-```typescript
-// Workflow tree
-expect(child.parent).toBe(parent);
-expect(parent.children).toContain(child);
-
-// Node tree (must match!)
-expect(child.node.parent).toBe(parent.node);
-expect(parent.node.children).toContain(child.node);
-```
-
----
-
-## External References
-
-For deeper understanding, see:
-
-1. **Full Research Document**
-   - `/home/dustin/projects/groundswell/plan/bugfix/P1M3T1S4/research/bidirectional-tree-consistency-testing.md`
-
-2. **Test Pattern Examples**
-   - `/home/dustin/projects/groundswell/plan/bugfix/P1M3T1S4/research/test-pattern-examples.md`
-
-3. **Research Summary**
-   - `/home/dustin/projects/groundswell/plan/bugfix/P1M3T1S4/research/SUMMARY.md`
-
-4. **Existing Test Examples**
-   - `/home/dustin/projects/groundswell/src/__tests__/integration/workflow-reparenting.test.ts`
-   - `/home/dustin/projects/groundswell/src/__tests__/adversarial/prd-compliance.test.ts`
-
----
-
-## Need Help?
-
-### For quick questions:
-- Check the "Test Pattern Examples" document for copy-paste templates
-- Look at existing tests in the codebase
-- Use the helper functions - they handle the complexity
-
-### For deep understanding:
-- Read the full research document
-- Study the existing test patterns
-- Review DOM and React Fiber patterns
-
-### For implementation:
-1. Create helper functions first
-2. Write tests using helpers
-3. Run tests, fix issues
-4. Iterate and refine
-
----
-
-**Remember**: The 1:1 tree mirror invariant is CRITICAL. If workflow tree and node tree don't match perfectly, bugs will occur. Always test both trees!
-
----
-
-**Quick Reference Version:** 1.0
-**Last Updated:** 2026-01-12
-**Maintainer:** P1M3T1S4 Research Team

package/plan/001_d3bb02af4886/docs/research/P1M3T1S4/README.md

@@ -1,305 +0,0 @@
-# Research: Testing Bidirectional Consistency Between Dual Tree Structures
-
-**Task:** P1M3T1S4
-**Research Date:** 2026-01-12
-**Status:** ✅ COMPLETE
-
----
-
-## Document Index
-
-This research package contains comprehensive documentation on testing patterns for bidirectional consistency between Workflow instance tree and WorkflowNode tree.
-
-### 📚 Documentation Files
-
-#### 1. QUICK_REFERENCE.md ⭐ **START HERE**
-**Best for:** Immediate use in writing tests
-**Contents:**
-- The golden rule of bidirectional consistency
-- Essential helper functions
-- Copy-paste test template
-- Critical invariants
-- Common test scenarios
-- Anti-patterns to avoid
-- Quick checklist
-
-**Read time:** 5 minutes
-**Use when:** Writing tests right now
-
----
-
-#### 2. test-pattern-examples.md
-**Best for:** Implementation with ready-to-use code
-**Contents:**
-- Complete helper functions implementation (600+ lines)
-- 6 complete test patterns with full code:
-  - Basic bidirectional consistency tests
-  - Reparenting consistency tests
-  - Invariant testing patterns
-  - Adversarial testing patterns
-  - Property-based testing patterns
-  - WorkflowTreeDebugger integration patterns
-- Test file template
-- Usage guidelines
-
-**Read time:** 15 minutes
-**Use when:** Implementing test suite
-
----
-
-#### 3. bidirectional-tree-consistency-testing.md
-**Best for:** Comprehensive understanding of patterns
-**Contents:**
-- Core testing patterns (AAA, naming conventions)
-- Bidirectional consistency validation methods
-- Tree operation testing (attach, detach, reparenting)
-- Invariant testing patterns (structural, counting, depth)
-- Adversarial testing approaches
-- External best practices (DOM, React Fiber, academic research)
-- Test pattern catalog
-- Implementation checklist
-
-**Read time:** 30 minutes
-**Use when:** Learning patterns deeply
-
----
-
-#### 4. SUMMARY.md
-**Best for:** Executive overview and roadmap
-**Contents:**
-- Executive summary
-- Key findings from codebase analysis
-- Actionable recommendations (prioritized)
-- URLs to all resources (internal and external)
-- Implementation roadmap (4-week plan)
-- Success metrics
-- Risk assessment
-
-**Read time:** 10 minutes
-**Use when:** Planning implementation strategy
-
----
-
-## Quick Start Guide
-
-### I Need to Write Tests Right Now 🚀
-1. Open **QUICK_REFERENCE.md**
-2. Copy the test template
-3. Use helper functions (verifyBidirectionalLink, verifyTreeMirror)
-4. Run tests
-
-### I Need to Implement Test Suite 🛠️
-1. Open **test-pattern-examples.md**
-2. Copy helper functions to `src/__tests__/helpers/tree-verification.ts`
-3. Copy test patterns to new test file
-4. Run and iterate
-
-### I Need to Understand the Patterns 📖
-1. Open **bidirectional-tree-consistency-testing.md**
-2. Read relevant sections
-3. Study code examples
-4. Apply to your tests
-
-### I Need to Plan Implementation 📋
-1. Open **SUMMARY.md**
-2. Review key findings
-3. Follow implementation roadmap
-4. Track progress with checklist
-
----
-
-## Key Takeaways
-
-### The Core Problem
-The codebase maintains TWO tree representations:
-1. **Workflow instance tree**: `workflow.parent`, `workflow.children`
-2. **WorkflowNode tree**: `node.parent`, `node.children`
-
-Both trees MUST stay perfectly synchronized (1:1 mirror invariant).
-
-### The Solution
-Test that every tree operation updates BOTH trees correctly:
-- Test parent→child AND child→parent directions
-- Test workflow tree AND node tree
-- Verify consistency after every operation
-
-### The Tools
-Helper functions make it easy:
-- `verifyBidirectionalLink(parent, child)` - Verify one link
-- `verifyTreeMirror(root)` - Verify entire tree
-- `validateTreeConsistency(root)` - Find all inconsistencies
-
----
-
-## Research Findings
-
-### ✅ What We Found
-
-1. **Strong Existing Patterns**
-   - Codebase already has excellent testing patterns
-   - Extracted and documented for reuse
-   - Example: `workflow-reparenting.test.ts:280-302`
-
-2. **Critical Invariant Identified**
-   - 1:1 tree mirror invariant is key to system correctness
-   - Must be verified after every tree mutation
-   - Both trees must perfectly correspond
-
-3. **External Validation**
-   - DOM API patterns align with our approach
-   - React Fiber dual tree pattern validates our design
-   - Academic research supports invariant testing methods
-
-4. **Actionable Patterns**
-   - 6+ test patterns documented with full code
-   - Helper functions ready to use
-   - Templates for quick implementation
-
-### 📊 Statistics
-
-- **Files Analyzed:** 7 test files + documentation
-- **Patterns Extracted:** 15+ distinct testing patterns
-- **Helper Functions:** 7 reusable utilities
-- **Code Examples:** 600+ lines of ready-to-use code
-- **Documentation:** 2,000+ lines of comprehensive guides
-
----
-
-## Implementation Roadmap
-
-### Phase 1: Foundation (Week 1) ⭐
-- [ ] Create helper functions library
-- [ ] Add helpers to existing tests
-- [ ] Verify no regressions
-
-**File to create:** `src/__tests__/helpers/tree-verification.ts`
-
-### Phase 2: Coverage (Week 2)
-- [ ] Create bidirectional consistency test suite
-- [ ] Add invariant tests
-- [ ] Achieve 95%+ coverage
-
-**File to create:** `src/__tests__/integration/bidirectional-consistency.test.ts`
-
-### Phase 3: Robustness (Week 3)
-- [ ] Create adversarial test suite
-- [ ] Add stress tests
-- [ ] Add property-based tests
-
-**File to create:** `src/__tests__/adversarial/tree-invariants.test.ts`
-
-### Phase 4: Integration (Week 4)
-- [ ] Add consistency checks to teardown
-- [ ] Integrate with CI/CD
-- [ ] Document patterns
-- [ ] Train team
-
----
-
-## URLs and References
-
-### Internal Resources
-- **Reparenting Tests:** `/home/dustin/projects/groundswell/src/__tests__/integration/workflow-reparenting.test.ts`
-- **Tree Mirroring Tests:** `/home/dustin/projects/groundswell/src/__tests__/integration/tree-mirroring.test.ts`
-- **PRD Compliance Tests:** `/home/dustin/projects/groundswell/src/__tests__/adversarial/prd-compliance.test.ts`
-- **Edge Case Tests:** `/home/dustin/projects/groundswell/src/__tests__/adversarial/edge-case.test.ts`
-- **Tree Debugger:** `/home/dustin/projects/groundswell/src/debugger/tree-debugger.ts`
-- **Implementation Patterns:** `/home/dustin/projects/groundswell/plan/docs/bugfix-architecture/implementation_patterns.md`
-
-### External Resources
-- **DOM Tree Spec:** https://dom.spec.whatwg.org/#concept-tree-parent
-- **React Fiber:** https://github.com/facebook/react/blob/main/packages/react-reconciler/src/ReactFiber.js
-- **QuickCheck Paper:** https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf
-- **Princeton CS226:** https://www.cs.princeton.edu/courses/archive/fall09/cos226/lectures/22BalancedTrees.pdf
-
----
-
-## Success Criteria
-
-### Quantitative
-- ✅ 50+ new bidirectional consistency tests
-- ✅ 95%+ coverage of tree manipulation code
-- ✅ Test suite completes in <5 minutes
-- ✅ 5+ potential issues caught by adversarial tests
-
-### Qualitative
-- ✅ High confidence in tree operation correctness
-- ✅ Easy to add new consistency tests
-- ✅ Clear patterns documented
-- ✅ Team trained on testing approach
-
----
-
-## FAQ
-
-**Q: Why do we need two trees?**
-A: Workflow instance tree provides runtime behavior, WorkflowNode tree provides introspection and debugging. Both must stay in sync.
-
-**Q: What happens if trees get out of sync?**
-A: Bugs occur. Events may not propagate correctly, debugging shows wrong structure, observers receive incorrect data.
-
-**Q: How do I know if my tests are good enough?**
-A: Use the helper functions! `verifyBidirectionalLink()` and `verifyTreeMirror()` catch most issues.
-
-**Q: Can I skip testing node tree if I test workflow tree?**
-A: NO! Both trees must be tested. The whole point is they must stay synchronized.
-
-**Q: Where do I start?**
-A: Start with QUICK_REFERENCE.md. It has everything you need to write tests immediately.
-
----
-
-## Support
-
-### Questions?
-- Check QUICK_REFERENCE.md for immediate answers
-- Review test-pattern-examples.md for code samples
-- Read bidirectional-tree-consistency-testing.md for deep understanding
-
-### Issues?
-- Verify you're testing both trees
-- Use helper functions consistently
-- Check existing test patterns for examples
-
-### Contributions?
-- Follow the patterns in this research
-- Use helper functions in new tests
-- Document new patterns as you discover them
-
----
-
-## Document Metadata
-
-**Research Task:** P1M3T1S4
-**Completion Date:** 2026-01-12
-**Status:** ✅ COMPLETE
-**Version:** 1.0
-
-**Documents:**
-1. QUICK_REFERENCE.md (5 min read)
-2. test-pattern-examples.md (15 min read)
-3. bidirectional-tree-consistency-testing.md (30 min read)
-4. SUMMARY.md (10 min read)
-5. README.md (this file)
-
-**Total Documentation:** 2,000+ lines
-**Total Code Examples:** 600+ lines
-**Helper Functions:** 7 reusable utilities
-
----
-
-## Next Steps
-
-1. **Read** QUICK_REFERENCE.md (5 minutes)
-2. **Create** helper functions library (1 hour)
-3. **Write** tests using patterns (2-4 hours)
-4. **Run** tests and verify (30 minutes)
-5. **Iterate** and refine (ongoing)
-
-**Ready to start? Open QUICK_REFERENCE.md!** →
-
----
-
-**Research Team:** P1M3T1S4
-**Last Updated:** 2026-01-12
-**Contact:** See project documentation for team contacts