groundswell 0.0.2 → 1.0.0

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

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