groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/docs/bugfix-architecture/bug_analysis.md

@@ -0,0 +1,415 @@
+# Bug Analysis: attachChild() Tree Integrity Violation
+
+## Bug Summary
+
+**Severity**: Critical
+**Location**: `src/core/workflow.ts:187-201` (attachChild method)
+**Discovered By**: Comprehensive end-to-end testing (240 existing tests + adversarial testing)
+**Impact**: Inconsistent tree state, broken observer propagation, data integrity violation
+
+## Bug Description
+
+The `attachChild()` method does not validate if a child workflow already has a parent before attaching it to a new parent. This allows a single child to appear in multiple parents' `children` arrays while only linking to one parent via its `parent` property, creating an inconsistent tree state.
+
+## Current Implementation (Buggy)
+
+```typescript
+// File: src/core/workflow.ts, lines 187-201
+public attachChild(child: Workflow): void {
+  // Only checks if already attached to THIS workflow
+  if (this.children.includes(child)) {
+    throw new Error('Child already attached to this workflow');
+  }
+
+  // NO VALIDATION: Does not check if child.parent is already set!
+
+  this.children.push(child);
+  this.node.children.push(child.node);
+
+  this.emitEvent({
+    type: 'childAttached',
+    parentId: this.id,
+    child: child.node,
+  });
+}
+```
+
+## Steps to Reproduce
+
+```typescript
+import { Workflow } from './src/index.js';
+
+const parent1 = new Workflow('Parent1');
+const parent2 = new Workflow('Parent2');
+
+// Create child with parent1 - child is automatically attached via constructor
+const child = new Workflow('Child', parent1);
+
+// BUG: attachChild doesn't check if child already has a parent
+parent2.attachChild(child);
+
+// Result: INCONSISTENT STATE
+console.log(child.parent === parent1);           // true (original parent)
+console.log(parent1.children.includes(child));    // true (still in parent1)
+console.log(parent2.children.includes(child));    // true (also in parent2!)
+console.log(child.parent === parent2);           // false (not updated)
+```
+
+## Impact Analysis
+
+### 1. Observer Event Propagation Failure
+
+**Problem**: Events from the shared child only propagate to the original parent's observers.
+
+```typescript
+const parent1 = new Workflow('Parent1');
+const parent2 = new Workflow('Parent2');
+const child = new Workflow('Child', parent1);
+
+parent2.attachChild(child); // Bug creates inconsistency
+
+// Add observers
+parent1.addObserver({ onEvent: (e) => console.log('P1:', e.type), ... });
+parent2.addObserver({ onEvent: (e) => console.log('P2:', e.type), ... });
+
+// Emit event from child
+child.emitEvent({ type: 'stepStart', ... });
+
+// Output:
+// P1: stepStart  ✅ (original parent receives it)
+//                ❌ (parent2 never receives it, even though child is in parent2.children!)
+```
+
+**Root Cause**: The `getRootObservers()` method follows the `child.parent` chain:
+```typescript
+protected getRootObservers(): WorkflowObserver[] {
+  // Only follows child.parent, which is parent1
+  let root = this;
+  while (root.parent) root = root.parent;
+  return root.observers;
+}
+```
+
+### 2. Tree Debugger Inconsistency
+
+**Problem**: Tree debugger shows child in both trees, but navigation is broken.
+
+```typescript
+import { WorkflowTreeDebugger } from './src/index.js';
+
+const debugger1 = new WorkflowTreeDebugger(parent1);
+const debugger2 = new WorkflowTreeDebugger(parent2);
+
+console.log(debugger1.toTreeString());
+// Parent1
+//   └─ Child ✅ (visible)
+
+console.log(debugger2.toTreeString());
+// Parent2
+//   └─ Child ✅ (visible)
+
+// But navigation via parent/child links:
+console.log(child.parent.node.name);  // "Parent1" (not Parent2!)
+console.log(parent2.children[0].parent === parent2);  // false!
+```
+
+### 3. getRoot() Returns Wrong Root
+
+**Problem**: The `getRoot()` method only follows the `child.parent` chain.
+
+```typescript
+const parent1 = new Workflow('Parent1');
+const parent2 = new Workflow('Parent2');
+const child = new Workflow('Child', parent1);
+
+parent2.attachChild(child);
+
+// getRoot() only follows child.parent
+console.log(child.getRoot());  // Returns parent1, NOT parent2
+// Even though child appears in parent2's tree!
+```
+
+### 4. Data Integrity Violation
+
+**Problem**: Violates PRD's "1:1 tree mirror" requirement.
+
+**PRD Section 12.2 Requirement**:
+> "A child workflow should have exactly one parent.
+> The `child.parent` property should always match the parent that contains it.
+> A child should only appear in one parent's `children` array."
+
+**Current Behavior**: All three requirements violated.
+
+## Why Existing Tests Didn't Catch This
+
+The existing 241 tests don't cover this scenario because:
+
+1. **Normal Usage**: Most tests create children with a parent and don't re-attach them
+2. **Constructor Pattern**: Using `new Workflow(name, parent)` automatically attaches, so explicit `attachChild()` calls are rare
+3. **Missing Adversarial Tests**: No tests explicitly try to attach a child that already has a different parent
+4. **Observer Tests**: Observer tests don't verify that events DON'T propagate to wrong parents
+
+## Root Cause
+
+The `attachChild()` method was designed with these assumptions:
+
+1. **Assumption 1**: Children are created without parents and attached later
+   - **Reality**: Constructor auto-attaches if parent is provided
+   - **Gap**: No validation for pre-existing parent
+
+2. **Assumption 2**: Developers will read the docs and not misuse the API
+   - **Reality**: API allows accidental misuse (no validation)
+   - **Gap**: No defensive programming for edge cases
+
+3. **Assumption 3**: The check `this.children.includes(child)` is sufficient
+   - **Reality**: Only prevents duplicates in THIS parent, not other parents
+   - **Gap**: No validation of child's current parent state
+
+## Solution Design
+
+### Primary Fix: Add Parent Validation
+
+```typescript
+public attachChild(child: Workflow): void {
+  // Validation 1: Prevent duplicate attachment to this workflow
+  if (this.children.includes(child)) {
+    throw new Error(
+      `Child '${child.node.name}' is already attached to workflow '${this.node.name}'`
+    );
+  }
+
+  // VALIDATION 2: Check if child already has a different parent (THE FIX)
+  if (child.parent !== null && child.parent !== this) {
+    throw new Error(
+      `Child '${child.node.name}' already has parent '${child.parent.node.name}'. ` +
+      `A workflow can only have one parent. ` +
+      `Use detachChild() on the current parent first if you need to reparent.`
+    );
+  }
+
+  // Update child's parent if it's currently null
+  if (child.parent === null) {
+    child.parent = this;
+  }
+
+  // Add to both trees
+  this.children.push(child);
+  this.node.children.push(child.node);
+
+  // Emit event
+  this.emitEvent({
+    type: 'childAttached',
+    parentId: this.id,
+    child: child.node,
+  });
+}
+```
+
+### Secondary Fix: Add Circular Reference Detection
+
+Prevent attaching an ancestor as a child (would create a cycle):
+
+```typescript
+public attachChild(child: Workflow): void {
+  // ... existing validations ...
+
+  // VALIDATION 3: Prevent circular references
+  if (this.isDescendantOf(child)) {
+    throw new Error(
+      `Cannot attach child '${child.node.name}' - it is an ancestor of '${this.node.name}'. ` +
+      `This would create a circular reference.`
+    );
+  }
+
+  // ... rest of method ...
+}
+
+/**
+ * Check if this workflow is a descendant of another workflow
+ */
+private isDescendantOf(ancestor: Workflow): boolean {
+  let current: Workflow | null = this;
+  const visited = new Set<Workflow>();
+
+  while (current !== null) {
+    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;
+}
+```
+
+### Tertiary Fix: Add detachChild() Method
+
+Enable proper reparenting workflow:
+
+```typescript
+/**
+ * Detach a child workflow from this parent
+ * @throws {Error} If child is not attached to this workflow
+ */
+public detachChild(child: Workflow): void {
+  const index = this.children.indexOf(child);
+  if (index === -1) {
+    throw new Error(
+      `Child '${child.node.name}' is not attached to workflow '${this.node.name}'`
+    );
+  }
+
+  // Remove from workflow children array
+  this.children.splice(index, 1);
+
+  // Remove from node children array
+  const nodeIndex = this.node.children.indexOf(child.node);
+  if (nodeIndex !== -1) {
+    this.node.children.splice(nodeIndex, 1);
+  }
+
+  // Clear child's parent reference
+  child.parent = null;
+
+  // Emit detached event for observers
+  this.emitEvent({
+    type: 'childDetached',
+    parentId: this.id,
+    childId: child.id,
+  });
+}
+```
+
+### Quaternary Fix: Update Event Types
+
+Add `childDetached` to the event type union:
+
+```typescript
+// File: src/types/events.ts
+export type WorkflowEvent =
+  | { type: 'stepStart'; node: WorkflowNode; step: string }
+  | { type: 'stepFinish'; node: WorkflowNode; step: string; result: unknown }
+  | { type: 'stateUpdated'; node: WorkflowNode; state: Record<string, unknown> }
+  | { type: 'childAttached'; parentId: string; child: WorkflowNode }
+  | { type: 'childDetached'; parentId: string; childId: string }  // NEW
+  | { type: 'treeUpdated'; node: WorkflowNode }
+  | { type: 'error'; node: WorkflowNode; error: WorkflowError };
+```
+
+## Test Coverage Requirements
+
+### Required New Tests
+
+1. **Prevent attaching child with existing parent**:
+   ```typescript
+   it('should throw when attaching child that already has a different parent')
+   ```
+
+2. **Allow attaching child with null parent**:
+   ```typescript
+   it('should attach child when child.parent is null')
+   ```
+
+3. **Prevent circular references**:
+   ```typescript
+   it('should throw when attaching ancestor as child (circular reference)')
+   ```
+
+4. **Prevent duplicate children**:
+   ```typescript
+   it('should throw when attaching same child twice to same parent')
+   ```
+
+5. **detachChild() removes child properly**:
+   ```typescript
+   it('should detach child and clear parent reference')
+   ```
+
+6. **Observer propagation after reparenting**:
+   ```typescript
+   it('should propagate events to new parent observers after reparenting')
+   ```
+
+7. **Bidirectional tree consistency**:
+   ```typescript
+   it('should maintain consistency between workflow tree and node tree')
+   ```
+
+8. **Adversarial: manual parent mutation**:
+   ```typescript
+   it('should handle manual parent mutation gracefully')
+   ```
+
+9. **Deep hierarchy without stack overflow**:
+   ```typescript
+   it('should handle 1000+ level deep hierarchies')
+   ```
+
+10. **Complex circular reference detection**:
+    ```typescript
+    it('should detect circular references in deep trees')
+    ```
+
+## Backward Compatibility
+
+### Breaking Changes
+
+**None**. This fix only prevents buggy behavior that was already incorrect.
+
+### Behavior Changes
+
+- **Before**: `attachChild()` would silently create inconsistent state
+- **After**: `attachChild()` throws clear error with guidance
+
+### Migration Path
+
+Users who were accidentally relying on the buggy behavior (e.g., attaching a child to multiple parents) will need to:
+
+1. **Option A**: Use only one parent (recommended)
+2. **Option B**: Implement reparenting with `detachChild()`:
+   ```typescript
+   // Before (buggy):
+   parent2.attachChild(child);  // Silent failure if child has parent
+
+   // After (correct):
+   if (child.parent) {
+     child.parent.detachChild(child);
+   }
+   parent2.attachChild(child);
+   ```
+
+## Validation Checklist
+
+- [ ] Implementation matches PRD Section 12.2 requirements
+- [ ] All 241 existing tests still pass
+- [ ] All new tests pass (10+ tests)
+- [ ] Observer events propagate correctly after fix
+- [ ] Tree debugger shows consistent trees
+- [ ] getRoot() returns correct root after fix
+- [ ] Error messages are clear and actionable
+- [ ] Circular reference detection works
+- [ ] Reparenting workflow works with detachChild()
+- [ ] Code follows existing patterns and style
+- [ ] Types are all correct (TypeScript compilation)
+- [ ] No performance regression
+
+## Success Metrics
+
+1. **Bug Fixed**: Cannot create inconsistent tree state
+2. **Tests Pass**: All 241+ tests pass
+3. **Observer Works**: Events propagate to correct observers
+4. **PRD Compliance**: Fully compliant with Section 12.2
+5. **Clear Errors**: Error messages guide users to solution
+6. **No Regression**: All existing functionality works as before
+
+## References
+
+- PRD Section 12.2: Workflow Base Class
+- File: `src/core/workflow.ts`, lines 187-201
+- Test File: `src/__tests__/adversarial/edge-case.test.ts`
+- Event Types: `src/types/events.ts`