groundswell 0.0.1 → 0.0.2

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

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

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