groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T2S1/README.md

@@ -0,0 +1,215 @@
+# Research Package: Tree Debugger Incremental Node Map Updates
+
+**Task**: P1.M3.T2.S1 - Analyze Tree Debugger onTreeChanged Implementation
+**Purpose**: Provide research resources for P1.M3.T2.S2 implementation and P1.M3.T2.S3 benchmark testing
+
+---
+
+## Main Research Package
+
+The comprehensive research package is located at:
+
+```
+plan/001_d3bb02af4886/docs/research/incremental-tree-map-updates/
+```
+
+### Key Files
+
+| File | Purpose | Size |
+|------|---------|------|
+| `QUICK_REFERENCE.md` | Code examples, URLs, gotchas | 9KB |
+| `RESEARCH_REPORT.md` | Comprehensive implementation analysis | 14KB |
+| `SUMMARY.md` | Executive summary | 5KB |
+| `PRP_TEMPLATE.md` | Ready-to-use implementation PRP | 15KB |
+
+---
+
+## External Documentation References
+
+### 1. MDN Web Docs - Map Instance Methods
+**URL**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#instance-methods
+
+**Key Insights**:
+- `Map.set()`, `Map.get()`, `Map.delete()` have **O(1)** average time complexity
+- Validates that incremental updates are faster than full O(n) rebuilds
+- Use as reference for implementation complexity analysis
+
+### 2. React Reconciliation Algorithm
+**URL**: https://react.dev/learn/understanding-reacts-render-phase
+
+**Key Insights**:
+- React only updates changed subtrees, not entire tree
+- Tree diffing strategy applicable to node map updates
+- Reference for "only process what changed" philosophy
+
+### 3. V8 Performance Optimization - Hidden Classes
+**URL**: https://v8.dev/blog/elements-kinds#hidden-classes
+
+**Key Insights**:
+- V8 optimizes Map operations with hidden classes
+- `Map.clear()` triggers large garbage collection operation
+- Incremental updates spread GC cost over time
+- Use for memory/GC impact analysis
+
+### 4. Stack Overflow - Map Time Complexity
+**URL**: https://stackoverflow.com/questions/38476433/what-is-the-time-complexity-of-map-set-in-javascript#answer-38476768
+
+**Key Insights**:
+- Confirmed **O(1)** complexity for Map.set(), Map.get(), Map.delete()
+- V8 and SpiderMonkey use hash table implementation
+- Use as authoritative reference for complexity claims
+
+### 5. Chrome DevTools Performance API
+**URL**: https://developer.chrome.com/docs/devtools/performance/#measure
+
+**Key Insights**:
+- `performance.mark()` and `performance.measure()` for benchmarking
+- Use as reference for P1.M3.T2.S3 benchmark test implementation
+
+---
+
+## Code Pattern Examples
+
+### BFS-Based Subtree Removal (Recommended)
+
+```typescript
+private removeSubtree(nodeId: string): void {
+  const node = this.nodeMap.get(nodeId);
+  if (!node) return;
+
+  // Collect all descendants using BFS (avoids stack overflow)
+  const toRemove: string[] = [];
+  const queue = [node];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    toRemove.push(current.id);
+    queue.push(...current.children);
+  }
+
+  // Remove all collected nodes
+  for (const id of toRemove) {
+    this.nodeMap.delete(id);
+  }
+}
+```
+
+**Why BFS instead of DFS?**
+- Avoids call stack overflow on deep trees
+- Same O(k) time complexity
+- Better memory locality with queue vs recursion stack
+
+---
+
+### Incremental Update Pattern
+
+```typescript
+onEvent(event: WorkflowEvent): void {
+  switch (event.type) {
+    case 'childAttached':
+      // ✅ O(k) - Add only new subtree
+      this.buildNodeMap(event.child);
+      break;
+
+    case 'childDetached':
+      // ✅ O(k) - Remove only detached subtree
+      this.removeSubtree(event.childId);
+      break;
+
+    case 'treeUpdated':
+      // ✅ O(1) - Just update root reference
+      this.root = event.root;
+      break;
+  }
+  this.events.next(event);
+}
+
+onTreeChanged(root: WorkflowNode): void {
+  // ✅ No rebuild needed - all updates handled in onEvent()
+  this.root = root;
+}
+```
+
+---
+
+## Performance Comparison
+
+| Operation | Current (Full Rebuild) | Incremental | Speedup |
+|-----------|----------------------|-------------|---------|
+| Add 1 node (1000 tree) | O(1000) | O(1) | **1000×** |
+| Remove 1 node (1000 tree) | O(1000) | O(1-10) | **100×** |
+| Update root reference | O(1000) | O(1) | **1000×** |
+
+---
+
+## Implementation Gotchas
+
+### ❌ Don't: Forget Subtree Cleanup
+
+```typescript
+// WRONG - Only removes detached node, leaves orphans
+onEvent(event: WorkflowEvent): void {
+  if (event.type === 'childDetached') {
+    this.nodeMap.delete(event.childId); // ❌ Orphaned descendants remain
+  }
+}
+```
+
+### ✅ Do: Remove Entire Subtree
+
+```typescript
+// CORRECT - Removes node and all descendants
+onEvent(event: WorkflowEvent): void {
+  if (event.type === 'childDetached') {
+    this.removeSubtree(event.childId); // ✅ Cleans entire subtree
+  }
+}
+```
+
+---
+
+## Benchmark Template (for P1.M3.T2.S3)
+
+```typescript
+import { performance } from 'perf_hooks';
+
+function benchmarkNodeMapUpdates() {
+  // Create 1000-node tree
+  const tree = createLargeTree(1000);
+  const debugger = new WorkflowTreeDebugger(tree);
+
+  // Benchmark: Single node attachment
+  const start = performance.now();
+  for (let i = 0; i < 1000; i++) {
+    const child = createNode(`child-${i}`);
+    tree.attachChild(child);
+  }
+  const end = performance.now();
+
+  console.log(`1000 attachments: ${end - start}ms`);
+  // Expected with incremental: <10ms
+  // Current with rebuild: >100ms
+}
+```
+
+---
+
+## Next Steps
+
+### For P1.M3.T2.S2 (Implementation):
+1. Read `QUICK_REFERENCE.md` for code examples
+2. Read `RESEARCH_REPORT.md` for detailed patterns
+3. Implement `removeSubtree()` method
+4. Modify `onEvent()` to handle `childDetached`
+5. Simplify `onTreeChanged()` to remove full rebuild
+
+### For P1.M3.T2.S3 (Benchmarks):
+1. Use benchmark template from this README
+2. Test with trees of varying sizes (10, 100, 1000 nodes)
+3. Measure before/after performance
+4. Document speedup achieved
+
+---
+
+**Research Package Created**: 2025-01-12
+**For Use By**: P1.M3.T2.S2 (Implementation), P1.M3.T2.S3 (Benchmarks)