groundswell 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3] - 2026-01-12
+
+### Fixed
+
+- **WorkflowLogger.child() signature** (Critical): Updated to accept `Partial<LogEntry>` parameter matching PRD specification, while maintaining backward compatibility with string-based API via function overloads.
+  - Implementation: [src/core/logger.ts:98-111](src/core/logger.ts#L98-L111)
+- **Promise.allSettled for concurrent tasks** (Major): Replaced `Promise.all()` with `Promise.allSettled()` for comprehensive error collection when multiple concurrent workflows fail, enabling aggregate error reporting.
+  - Implementation: [src/decorators/task.ts:112-142](src/decorators/task.ts#L112-L142)
+- **ErrorMergeStrategy implementation** (Major): Added error merge strategy for concurrent task failures with configurable custom combinators, enabling aggregation of all concurrent errors into a single WorkflowError.
+  - Implementation: [src/types/decorators.ts:25-32](src/types/decorators.ts#L25-L32), [src/utils/workflow-error-utils.ts:23-56](src/utils/workflow-error-utils.ts#L23-L56)
+- **Console.error to logger replacement** (Minor): Replaced `console.error()` with workflow logger for observer error handling, ensuring consistent structured logging throughout the codebase.
+  - Implementation: [src/core/workflow.ts:426, 444](src/core/workflow.ts#L426)
+- **Tree debugger optimization** (Minor): Implemented incremental node map updates for childDetached events using BFS traversal, avoiding O(n) full map rebuilds and improving performance on large workflow trees.
+  - Implementation: [src/debugger/tree-debugger.ts:65-84, 92-117](src/debugger/tree-debugger.ts#L65-L84)
+- **Workflow name validation** (Minor): Added validation for empty, whitespace-only, and overly long (>100 chars) workflow names to prevent invalid configurations.
+  - Implementation: [src/core/workflow.ts:98-107](src/core/workflow.ts#L98-L107)
+- **trackTiming default documentation** (Major): Clarified documentation that `trackTiming` in `@Step` decorator defaults to `true` via `!== false` check, improving API discoverability.
+  - Implementation: [src/decorators/step.ts:94-101](src/decorators/step.ts#L94-L101)
+- **isDescendantOf public API** (Minor): Made previously private `isDescendantOf()` helper method public with comprehensive JSDoc documentation, enabling workflow hierarchy validation and topology checking.
+  - Implementation: [src/core/workflow.ts:201-219](src/core/workflow.ts#L201-L219)
+
+### Added
+
+- **Public isDescendantOf() method**: Made the previously private `isDescendantOf()` helper method public for workflow hierarchy validation, circular reference prevention, and topology checking.
+  - Implementation: [src/core/workflow.ts:201-219](src/core/workflow.ts#L201-L219)
+
+### Test Coverage
+
+**New Test Files Added** (12 files):
+- `src/__tests__/unit/logger.test.ts` - WorkflowLogger.child() signature tests (294 lines)
+- `src/__tests__/adversarial/concurrent-task-failures.test.ts` - Concurrent task failure scenarios
+- `src/__tests__/adversarial/error-merge-strategy.test.ts` - Error merge strategy functionality
+- `src/__tests__/unit/tree-debugger-incremental.test.ts` - Incremental node map updates
+- `src/__tests__/adversarial/node-map-update-benchmarks.test.ts` - Performance benchmarks
+- `src/__tests__/integration/observer-logging.test.ts` - Observer logging tests
+- `src/__tests__/unit/workflow.test.ts` - Workflow name validation
+- `src/__tests__/unit/workflow-isDescendantOf.test.ts` - Public isDescendantOf API
+- `src/__tests__/adversarial/parent-validation.test.ts` - Parent validation edge cases
+- `src/__tests__/adversarial/circular-reference.test.ts` - Circular reference detection
+- `src/__tests__/adversarial/complex-circular-reference.test.ts` - Deep circular reference scenarios
+- `src/__tests__/integration/workflow-reparenting.test.ts` - Reparenting workflow tests
+
+**Test Count Increase**: +50+ new test cases
+**Regression Tests**: All existing tests continue to pass (100% pass rate maintained)
+
+### Implementation Details
+
+- **WorkflowLogger.child() signature fix**: [src/core/logger.ts:98-111](src/core/logger.ts#L98-L111)
+  - Function overloads for type safety with both string and Partial<LogEntry> parameters
+  - Backward compatible with existing string-based API
+  - Follows PRD specification exactly
+- **Promise.allSettled for concurrent tasks**: [src/decorators/task.ts:112-142](src/decorators/task.ts#L112-L142)
+  - Captures all concurrent errors using Promise.allSettled()
+  - Optional error merge strategy for aggregate error reporting
+  - Backward compatible: throws first error by default
+- **ErrorMergeStrategy implementation**: [src/types/decorators.ts:25-32](src/types/decorators.ts#L25-L32), [src/utils/workflow-error-utils.ts:23-56](src/utils/workflow-error-utils.ts#L23-L56)
+  - New TaskOptions.errorMergeStrategy property
+  - Default merger aggregates all error messages, logs, and workflow IDs
+  - Custom combine function support for specialized error handling
+- **Console.error to logger replacement**: [src/core/workflow.ts:426, 444](src/core/workflow.ts#L426)
+  - Observer onEvent errors now logged with structured context
+  - Observer onStateUpdated errors now logged with node context
+- **Tree debugger optimization**: [src/debugger/tree-debugger.ts:65-84, 92-117](src/debugger/tree-debugger.ts#L65-L84)
+  - Incremental subtree removal using BFS traversal
+  - O(k) complexity for subtree operations instead of O(n)
+  - Prevents stack overflow on deep trees with iterative BFS
+- **Workflow name validation**: [src/core/workflow.ts:98-107](src/core/workflow.ts#L98-L107)
+  - Rejects empty and whitespace-only names
+  - Rejects names exceeding 100 characters
+  - Fail-fast validation during construction
+- **trackTiming default documentation**: [src/decorators/step.ts:94-101](src/decorators/step.ts#L94-L101)
+  - Clarified that trackTiming defaults to true via !== false check
+  - Explicit false disables timing, undefined/true enables timing
+- **isDescendantOf public API**: [src/core/workflow.ts:201-219](src/core/workflow.ts#L201-L219)
+  - Cycle detection during parent chain traversal
+  - Comprehensive JSDoc with security warning and usage examples
+  - Time/space complexity documentation
+
+## [0.0.2] - 2026-01-12
+
+### Fixed
+
+- **attachChild() parent validation**: `attachChild()` now throws an Error if you attempt to attach a child that already has a different parent. Previously, this would silently create an inconsistent tree state where the child appeared in multiple parents' `children` arrays while only linking to one parent via its `parent` property.
+- **Circular reference detection**: `attachChild()` now detects and prevents attaching an ancestor as a child, which would create a circular reference in the tree.
+- **Observer event propagation**: Observer events now propagate correctly after reparenting operations. Previously, events from a shared child would only reach the original parent's observers, not any new parents.
+
+### Added
+
+- **New `detachChild()` method**: Enables proper reparenting workflow by removing a child from both the workflow tree (`this.children`) and the node tree (`this.node.children`), clearing the child's parent reference, and emitting a `childDetached` event.
+  - Implementation: [src/core/workflow.ts:329-358](src/core/workflow.ts#L329-L358)
+- **New `childDetached` event type**: Discriminated union member for detachment notifications, following the existing event pattern with `type`, `parentId`, and `childId` properties.
+  - Implementation: [src/types/events.ts:11](src/types/events.ts#L11)
+- **New `isDescendantOf()` helper**: Private method for circular reference detection that traverses the parent chain upward with cycle detection.
+  - Implementation: [src/core/workflow.ts:151-169](src/core/workflow.ts#L151-L169)
+
+### Migration Guide for attachChild() Behavior Change
+
+**What Changed**:
+The `attachChild()` method now throws an Error if you attempt to attach a child that already has a different parent. Previously, this would silently create an inconsistent tree state that broke observer propagation and violated the PRD's single-parent requirement.
+
+**Before (Buggy Pattern)**:
+```typescript
+// This would silently create inconsistent state
+const parent1 = new Workflow({ name: 'parent1' });
+const parent2 = new Workflow({ name: 'parent2' });
+const child = new Workflow({ name: 'child' });
+
+parent1.attachChild(child);  // child.parent = parent1
+parent2.attachChild(child);  // BUG: child still has parent1, but parent2 thinks it's attached
+// Result: child.parent === parent1, but parent2.children.includes(child) === true
+```
+
+**After (Correct Pattern)**:
+```typescript
+// Use detachChild() before reattaching
+const parent1 = new Workflow({ name: 'parent1' });
+const parent2 = new Workflow({ name: 'parent2' });
+const child = new Workflow({ name: 'child' });
+
+parent1.attachChild(child);
+parent1.detachChild(child);  // Explicitly detach first
+parent2.attachChild(child);  // Now works correctly
+// Result: child.parent === parent2, parent1.children does NOT include child
+```
+
+**Migration Steps**:
+1. Search your code for patterns of attaching the same child to multiple parents
+2. Add `detachChild()` calls before reattaching to a new parent
+3. Test that your workflow tree operations complete without errors
+4. Verify observer events propagate correctly after reparenting
+
+### Test Coverage
+
+**New Test Files Added** (12 files):
+- `src/__tests__/unit/workflow-detachChild.test.ts` - `detachChild()` method tests
+- `src/__tests__/unit/workflow-emitEvent-childDetached.test.ts` - `childDetached` event tests
+- `src/__tests__/adversarial/parent-validation.test.ts` - Parent validation edge cases
+- `src/__tests__/adversarial/circular-reference.test.ts` - Circular reference detection
+- `src/__tests__/adversarial/complex-circular-reference.test.ts` - Deep circular reference scenarios
+- `src/__tests__/adversarial/attachChild-performance.test.ts` - Performance validation
+- `src/__tests__/adversarial/deep-hierarchy-stress.test.ts` - Deep nesting tests (1000+ levels)
+- `src/__tests__/adversarial/bidirectional-consistency.test.ts` - Tree consistency tests
+- `src/__tests__/adversarial/edge-case.test.ts` - Edge case coverage
+- `src/__tests__/adversarial/observer-propagation.test.ts` - Observer propagation validation
+- `src/__tests__/adversarial/deep-analysis.test.ts` - Comprehensive deep tree analysis
+- `src/__tests__/integration/workflow-reparenting.test.ts` - Reparenting workflow tests
+
+**Test Count Increase**: +25 new test cases
+**Regression Tests**: All existing tests continue to pass (100% pass rate maintained)
+
+### Implementation Details
+
+- **attachChild() validation**: [src/core/workflow.ts:266-305](src/core/workflow.ts#L266-L305)
+  - Validates child is not already attached to this workflow
+  - Validates child does not have a different parent (throws with helpful error message)
+  - Validates child is not an ancestor of this parent (circular reference detection)
+- **detachChild() method**: [src/core/workflow.ts:329-358](src/core/workflow.ts#L329-L358)
+  - Removes child from both workflow and node trees
+  - Clears child's parent reference
+  - Emits childDetached event for observer notification
+- **isDescendantOf() helper**: [src/core/workflow.ts:151-169](src/core/workflow.ts#L151-L169)
+  - Private helper method for circular reference detection
+  - Traverses parent chain with Set-based cycle detection
+- **childDetached event**: [src/types/events.ts:11](src/types/events.ts#L11)
+  - Follows existing discriminated union pattern
+  - Uses `childId` (string) instead of `child` (WorkflowNode) since child is no longer in tree
+
+## [0.0.1] - 2025-01-10
+
+### Added
+- Initial release with hierarchical workflow engine
+- `Workflow` base class with parent/child relationships
+- Observer pattern for event propagation
+- `WorkflowTreeDebugger` for real-time tree visualization
+- `@Step`, `@Task`, and `@ObservedState` decorators
+- Full TypeScript type definitions
+
+[Unreleased]: https://github.com/dustin/groundswell/compare/v0.0.3...HEAD
+[0.0.3]: https://github.com/dustin/groundswell/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/dustin/groundswell/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/dustin/groundswell/releases/tag/v0.0.1

package/README.md

@@ -113,16 +113,110 @@ Immutable value objects defining what to send to an agent and how to validate th
 
 ## Decorators
 
+### @Step
+
+Emit lifecycle events and track step execution timing.
+
+**Default Behavior**: Without any options, `@Step()` automatically tracks timing information.
+
 ```typescript
-// Emit lifecycle events and track timing
-@Step({ trackTiming: true, snapshotState: true })
+@Step()  // Timing tracked by default
 async processData(): Promise<void> { }
+```
+
+**Configuration Options**:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | method name | Custom step name |
+| `trackTiming` | `boolean` | `true` | Include duration in `stepEnd` event. Set to `false` to eliminate timing overhead. |
+| `snapshotState` | `boolean` | `false` | Capture state snapshot after step completion |
+| `logStart` | `boolean` | `false` | Log message at step start |
+| `logFinish` | `boolean` | `false` | Log message at step end (includes duration) |
+
+**Examples**:
+
+```typescript
+// Default behavior - timing tracked automatically
+@Step()
+async basicStep(): Promise<void> { }
+
+// Disable timing for performance-critical code
+@Step({ trackTiming: false })
+async highFrequencyStep(): Promise<void> { }
+
+// Full configuration
+@Step({ trackTiming: true, snapshotState: true, logStart: true })
+async monitoredStep(): Promise<void> { }
+```
+
+**Performance Note**: Timing tracking has minimal overhead. Disable `trackTiming` only in performance-critical code paths with high-frequency execution.
+
+### @Task
+
+Spawn and manage child workflows.
+
+**Validation Behavior**: The decorator performs lenient validation - methods returning non-Workflow objects are silently skipped rather than throwing errors. This enables flexible method designs and duck-typing.
+
+**Configuration Options**:
 
-// Spawn and manage child workflows
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | method name | Custom task name |
+| `concurrent` | `boolean` | `false` | If `true`, automatically run returned workflows in parallel using `Promise.all()` |
+
+**How It Works**:
+- Workflow objects (with `id` property) are automatically attached as children
+- Non-workflow objects are silently skipped (not attached)
+- The original return value is always preserved
+- Duck-typing is used: any object with an `id` property is treated as workflow-like
+
+**Examples**:
+
+```typescript
+// Standard usage - return single workflow
+@Task()
+async createChild(): Promise<ChildWorkflow> {
+  return new ChildWorkflow('child1', this);  // Attached as child
+}
+
+// Return multiple workflows
 @Task({ concurrent: true })
-async createWorkers(): Promise<WorkerWorkflow[]> { }
+async createWorkers(): Promise<WorkerWorkflow[]> {
+  return [
+    new WorkerWorkflow('worker1', 100, this),  // Attached
+    new WorkerWorkflow('worker2', 150, this),  // Attached
+  ];  // Both run concurrently
+}
+
+// Mixed return - only workflows are attached
+@Task()
+async mixedReturn(): Promise<(Workflow | string)[]> {
+  return [
+    new ChildWorkflow('child1', this),  // Attached
+    'some string',                       // Skipped (not a workflow)
+    new ChildWorkflow('child2', this),  // Attached
+  ];
+}
+
+// Non-workflow return - handled gracefully
+@Task()
+async returnsData(): Promise<string> {
+  return 'just some data';  // Returned as-is, no attachment attempted
+}
+```
 
-// Mark fields for state snapshots
+**Important Notes**:
+- The decorator uses structural typing (duck-typing) via the `id` property check
+- This enables working with workflow-like objects, not just `Workflow` class instances
+- TypeScript compile-time type checking still catches obvious errors
+- Use `concurrent: true` for automatic parallel execution of returned workflows
+
+### @ObservedState
+
+Mark fields for state snapshots.
+
+```typescript
 @ObservedState()
 progress: number = 0;
 

package/dist/__tests__/adversarial/attachChild-performance.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Performance Test: attachChild() with isDescendantOf() validation
+ *
+ * Validates that the isDescendantOf() method (added in P1.M1.T2.S2)
+ * does not cause significant performance degradation in attachChild()
+ * operations across various tree sizes and configurations.
+ *
+ * Performance Thresholds (from deep-hierarchy-stress.test.ts):
+ * - Single operation: < 100ms
+ * - Bulk operations (100 iterations): < 1000ms
+ * - isDescendantOf() complexity: O(d) where d = tree depth
+ *
+ * Related: plan/bugfix/P1M4T2S2/PRP.md
+ */
+export {};
+//# sourceMappingURL=attachChild-performance.test.d.ts.map

package/dist/__tests__/adversarial/attachChild-performance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachChild-performance.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/adversarial/attachChild-performance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/__tests__/adversarial/attachChild-performance.test.js

@@ -0,0 +1,187 @@
+/**
+ * Performance Test: attachChild() with isDescendantOf() validation
+ *
+ * Validates that the isDescendantOf() method (added in P1.M1.T2.S2)
+ * does not cause significant performance degradation in attachChild()
+ * operations across various tree sizes and configurations.
+ *
+ * Performance Thresholds (from deep-hierarchy-stress.test.ts):
+ * - Single operation: < 100ms
+ * - Bulk operations (100 iterations): < 1000ms
+ * - isDescendantOf() complexity: O(d) where d = tree depth
+ *
+ * Related: plan/bugfix/P1M4T2S2/PRP.md
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Workflow } from '../../index.js';
+import { validateTreeConsistency, verifyBidirectionalLink } from '../helpers/tree-verification.js';
+/**
+ * SimpleWorkflow class for performance testing
+ * Pattern from: src/__tests__/adversarial/deep-hierarchy-stress.test.ts:20-26
+ */
+class SimpleWorkflow extends Workflow {
+    async run() {
+        this.setStatus('running');
+        this.setStatus('completed');
+        return 'done';
+    }
+}
+describe('attachChild Performance Regression Tests', () => {
+    /**
+     * Setup: Mock console methods to capture error messages
+     * Pattern from: src/__tests__/adversarial/deep-hierarchy-stress.test.ts:33-37
+     */
+    beforeEach(() => {
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        vi.spyOn(console, 'error').mockImplementation(() => { });
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    /**
+     * Teardown: Restore all mocks to prevent test pollution
+     * CRITICAL: Always use vi.restoreAllMocks() in afterEach
+     */
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    /**
+     * Test 1: Shallow tree performance (depth 10)
+     *
+     * Validates that attachChild() performs very fast on shallow trees
+     * where isDescendantOf() only needs to traverse a short parent chain.
+     *
+     * Threshold: < 10ms (should be very fast for shallow trees)
+     */
+    it('should attach child in shallow tree within acceptable time', () => {
+        // ARRANGE: Create shallow tree (depth 10)
+        const DEPTH = 10;
+        const root = new SimpleWorkflow('Root');
+        let current = root;
+        for (let i = 0; i < DEPTH; i++) {
+            current = new SimpleWorkflow(`Level-${i}`, current);
+        }
+        // ACT: Measure attachChild() time for new child at depth 10
+        const startTime = performance.now();
+        const newChild = new SimpleWorkflow('NewChild', current);
+        const attachDuration = performance.now() - startTime;
+        // ASSERT: Verify functional correctness
+        expect(newChild.parent).toBe(current);
+        expect(current.children).toContain(newChild);
+        verifyBidirectionalLink(current, newChild);
+        // ASSERT: Verify performance threshold (< 10ms for shallow tree)
+        expect(attachDuration).toBeLessThan(10);
+    });
+    /**
+     * Test 2: Deep tree performance (depth 100)
+     *
+     * Validates that attachChild() scales linearly with tree depth.
+     * isDescendantOf() must traverse 100 parent references, which should
+     * complete in < 50ms given the O(d) iterative implementation.
+     *
+     * Threshold: < 50ms (linear scaling with depth)
+     */
+    it('should attach child in deep tree (depth 100) within acceptable time', () => {
+        // ARRANGE: Create deep tree
+        const DEPTH = 100;
+        const root = new SimpleWorkflow('Root');
+        let current = root;
+        for (let i = 0; i < DEPTH; i++) {
+            current = new SimpleWorkflow(`Child-${i}`, current);
+        }
+        // ACT: Measure attachChild() at deepest level
+        const startTime = performance.now();
+        const newChild = new SimpleWorkflow('NewChild', current);
+        const attachDuration = performance.now() - startTime;
+        // ASSERT: Functional correctness
+        verifyBidirectionalLink(current, newChild);
+        // ASSERT: Performance threshold (< 50ms for depth 100)
+        expect(attachDuration).toBeLessThan(50);
+        // ASSERT: Validate overall tree consistency
+        const errors = validateTreeConsistency(root);
+        expect(errors).toHaveLength(0);
+    });
+    /**
+     * Test 3: Extreme deep tree (depth 1000)
+     *
+     * Validates that attachChild() handles extreme depth without stack overflow
+     * and completes within acceptable time. This tests the O(d) complexity
+     * at the upper bound of typical workflow tree depths.
+     *
+     * Threshold: < 100ms (from deep-hierarchy-stress.test.ts:169)
+     */
+    it('should attach child in extreme deep tree (depth 1000) without stack overflow', () => {
+        const DEPTH = 1000;
+        const root = new SimpleWorkflow('Root');
+        let current = root;
+        for (let i = 0; i < DEPTH; i++) {
+            current = new SimpleWorkflow(`Child-${i}`, current);
+        }
+        // ACT: Measure attachChild() at depth 1000
+        const startTime = performance.now();
+        const newChild = new SimpleWorkflow('NewChild', current);
+        const attachDuration = performance.now() - startTime;
+        // ASSERT: Functional correctness
+        verifyBidirectionalLink(current, newChild);
+        // ASSERT: Performance threshold (< 100ms from deep-hierarchy-stress.test.ts:169)
+        expect(attachDuration).toBeLessThan(100);
+        // ASSERT: Validate tree consistency at extreme depth
+        const errors = validateTreeConsistency(root);
+        expect(errors).toHaveLength(0);
+    });
+    /**
+     * Test 4: Wide tree performance (100 children)
+     *
+     * Validates that attachChild() performs efficiently when attaching
+     * multiple children to a single parent. Each attachment only requires
+     * checking immediate parent chain, so performance should be excellent.
+     *
+     * Threshold: < 100ms total, < 1ms average per attachment
+     */
+    it('should attach 100 children to single parent efficiently', () => {
+        // ARRANGE: Create parent
+        const parent = new SimpleWorkflow('Parent');
+        const NUM_CHILDREN = 100;
+        // ACT: Measure time to attach all children
+        const startTime = performance.now();
+        for (let i = 0; i < NUM_CHILDREN; i++) {
+            const child = new SimpleWorkflow(`Child-${i}`, parent);
+        }
+        const totalDuration = performance.now() - startTime;
+        // ASSERT: Verify all children attached
+        expect(parent.children).toHaveLength(NUM_CHILDREN);
+        parent.children.forEach(child => {
+            verifyBidirectionalLink(parent, child);
+        });
+        // ASSERT: Performance (< 100ms total, < 1ms average)
+        expect(totalDuration).toBeLessThan(100);
+        const avgTime = totalDuration / NUM_CHILDREN;
+        expect(avgTime).toBeLessThan(1); // < 1ms per attachment
+    });
+    /**
+     * Test 5: Bulk attachment performance (100 operations)
+     *
+     * Validates that sequential attachChild() operations complete within
+     * acceptable time. This measures cumulative overhead of isDescendantOf()
+     * validation across multiple operations.
+     *
+     * Threshold: < 1000ms (from deep-hierarchy-stress.test.ts:186)
+     */
+    it('should complete 100 sequential attachChild operations within acceptable time', () => {
+        // ARRANGE: Create root workflow
+        const root = new SimpleWorkflow('Root');
+        const ITERATIONS = 100;
+        // ACT: Measure cumulative time for 100 attachments
+        const totalStartTime = performance.now();
+        for (let i = 0; i < ITERATIONS; i++) {
+            const child = new SimpleWorkflow(`Child-${i}`, root);
+        }
+        const totalDuration = performance.now() - totalStartTime;
+        // ASSERT: Verify functional correctness
+        expect(root.children).toHaveLength(ITERATIONS);
+        // ASSERT: Performance threshold (< 1000ms from deep-hierarchy-stress.test.ts:186)
+        expect(totalDuration).toBeLessThan(1000);
+        // ASSERT: Average time per operation
+        const avgTime = totalDuration / ITERATIONS;
+        expect(avgTime).toBeLessThan(10); // < 10ms average
+    });
+});
+//# sourceMappingURL=attachChild-performance.test.js.map

package/dist/__tests__/adversarial/attachChild-performance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachChild-performance.test.js","sourceRoot":"","sources":["../../../src/__tests__/adversarial/attachChild-performance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAEnG;;;GAGG;AACH,MAAM,cAAe,SAAQ,QAAQ;IACnC,KAAK,CAAC,GAAG;QACP,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC1B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,QAAQ,CAAC,0CAA0C,EAAE,GAAG,EAAE;IACxD;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACtD,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACxD,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH;;;;;;;OAOG;IACH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,0CAA0C;QAC1C,MAAM,KAAK,GAAG,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,OAAO,GAAQ,IAAI,CAAC;QAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,OAAO,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;QAED,4DAA4D;QAC5D,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAErD,wCAAwC;QACxC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC7C,uBAAuB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAE3C,iEAAiE;QACjE,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH;;;;;;;;OAQG;IACH,EAAE,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC7E,4BAA4B;QAC5B,MAAM,KAAK,GAAG,GAAG,CAAC;QAClB,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,OAAO,GAAQ,IAAI,CAAC;QAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,OAAO,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;QAED,8CAA8C;QAC9C,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAErD,iCAAiC;QACjC,uBAAuB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAE3C,uDAAuD;QACvD,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QAExC,4CAA4C;QAC5C,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH;;;;;;;;OAQG;IACH,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,KAAK,GAAG,IAAI,CAAC;QACnB,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,OAAO,GAAQ,IAAI,CAAC;QAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,OAAO,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;QAED,2CAA2C;QAC3C,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAErD,iCAAiC;QACjC,uBAAuB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAE3C,iFAAiF;QACjF,MAAM,CAAC,cAAc,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAEzC,qDAAqD;QACrD,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH;;;;;;;;OAQG;IACH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,yBAAyB;QACzB,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,YAAY,GAAG,GAAG,CAAC;QAEzB,2CAA2C;QAC3C,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAEpD,uCAAuC;QACvC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;QACnD,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;YAC9B,uBAAuB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,qDAAqD;QACrD,MAAM,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,aAAa,GAAG,YAAY,CAAC;QAC7C,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB;IAC1D,CAAC,CAAC,CAAC;IAEH;;;;;;;;OAQG;IACH,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,gCAAgC;QAChC,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,GAAG,CAAC;QAEvB,mDAAmD;QACnD,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;QAEzD,wCAAwC;QACxC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QAE/C,kFAAkF;QAClF,MAAM,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAEzC,qCAAqC;QACrC,MAAM,OAAO,GAAG,aAAa,GAAG,UAAU,CAAC;QAC3C,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/adversarial/circular-reference.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Circular Reference Tests (TDD Red Phase)
+ *
+ * These tests validate the attachChild() method properly prevents
+ * attaching an ancestor workflow as a child (which would create a circular reference).
+ *
+ * This is the RED phase of TDD - tests are written to FAIL initially,
+ * documenting the expected behavior before implementation.
+ *
+ * Related: plan/docs/bugfix-architecture/bug_analysis.md
+ */
+export {};
+//# sourceMappingURL=circular-reference.test.d.ts.map

package/dist/__tests__/adversarial/circular-reference.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circular-reference.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/adversarial/circular-reference.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/__tests__/adversarial/circular-reference.test.js

@@ -0,0 +1,92 @@
+/**
+ * Circular Reference Tests (TDD Red Phase)
+ *
+ * These tests validate the attachChild() method properly prevents
+ * attaching an ancestor workflow as a child (which would create a circular reference).
+ *
+ * This is the RED phase of TDD - tests are written to FAIL initially,
+ * documenting the expected behavior before implementation.
+ *
+ * Related: plan/docs/bugfix-architecture/bug_analysis.md
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Workflow } from '../../index.js';
+/**
+ * SimpleWorkflow class for testing
+ * Pattern from: src/__tests__/unit/workflow.test.ts:4-11
+ */
+class SimpleWorkflow extends Workflow {
+    async run() {
+        this.setStatus('running');
+        this.setStatus('completed');
+        return 'done';
+    }
+}
+describe('Adversarial: Circular Reference Detection', () => {
+    /**
+     * Setup: Mock console methods to capture error messages
+     * Pattern from: research/console-mocking.md "Basic Spying Patterns"
+     */
+    beforeEach(() => {
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        vi.spyOn(console, 'error').mockImplementation(() => { });
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    /**
+     * Teardown: Restore all mocks to prevent test pollution
+     * CRITICAL: Always use vi.restoreAllMocks() in afterEach
+     */
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    /**
+     * Test 1: Immediate Circular Reference
+     *
+     * Bug: attachChild() does NOT check if the child being attached is actually
+     * an ancestor of this workflow (would create a circular reference)
+     *
+     * Expected: Error thrown with message containing 'circular' OR 'cycle' OR 'ancestor'
+     * Actual: No error thrown, circular reference created
+     *
+     * Pattern from: plan/docs/bugfix-architecture/implementation_patterns.md "Pattern 2"
+     */
+    it('should throw when attaching immediate parent as child', () => {
+        // ARRANGE: Create parent and child workflows
+        const parent = new SimpleWorkflow('Parent');
+        const child = new SimpleWorkflow('Child', parent);
+        // Verify initial state
+        // CRITICAL: Constructor auto-attaches child to parent at workflow.ts:113-116
+        expect(child.parent).toBe(parent);
+        expect(parent.children).toContain(child);
+        // ACT & ASSERT: Attempting to attach parent as child should throw
+        // This test FAILS because attachChild() doesn't call this.isDescendantOf(child)
+        expect(() => child.attachChild(parent)).toThrow(/circular|cycle|ancestor/i);
+    });
+    /**
+     * Test 2: Ancestor Circular Reference (Multi-level)
+     *
+     * Bug: attachChild() does NOT check if the child being attached is an ancestor
+     * anywhere up the parent chain (would create a circular reference)
+     *
+     * Expected: Error thrown with message containing 'circular' OR 'cycle' OR 'ancestor'
+     * Actual: No error thrown, circular reference created
+     *
+     * Pattern from: plan/docs/bugfix-architecture/implementation_patterns.md "Pattern 2"
+     */
+    it('should throw when attaching ancestor as child', () => {
+        // ARRANGE: Create 3-level hierarchy
+        const root = new SimpleWorkflow('Root');
+        const child1 = new SimpleWorkflow('Child1', root);
+        const child2 = new SimpleWorkflow('Child2', child1);
+        // Verify initial state
+        // CRITICAL: Constructor auto-attaches at workflow.ts:113-116
+        expect(child2.parent).toBe(child1);
+        expect(child1.parent).toBe(root);
+        expect(root.children).toContain(child1);
+        expect(child1.children).toContain(child2);
+        // ACT & ASSERT: Attempting to attach root as child of child2 should throw
+        // This test FAILS because attachChild() doesn't call this.isDescendantOf(child)
+        expect(() => child2.attachChild(root)).toThrow(/circular|cycle|ancestor/i);
+    });
+});
+//# sourceMappingURL=circular-reference.test.js.map

package/dist/__tests__/adversarial/circular-reference.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circular-reference.test.js","sourceRoot":"","sources":["../../../src/__tests__/adversarial/circular-reference.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;GAGG;AACH,MAAM,cAAe,SAAQ,QAAQ;IACnC,KAAK,CAAC,GAAG;QACP,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC1B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,QAAQ,CAAC,2CAA2C,EAAE,GAAG,EAAE;IACzD;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACtD,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACxD,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH;;;;;;;;;;OAUG;IACH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,6CAA6C;QAC7C,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAElD,uBAAuB;QACvB,6EAA6E;QAC7E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAEzC,kEAAkE;QAClE,gFAAgF;QAChF,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH;;;;;;;;;;OAUG;IACH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,oCAAoC;QACpC,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEpD,uBAAuB;QACvB,6DAA6D;QAC7D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE1C,0EAA0E;QAC1E,gFAAgF;QAChF,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/adversarial/complex-circular-reference.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Complex Circular Reference Tests
+ *
+ * These tests validate that isDescendantOf() correctly detects circular
+ * references at various depths in the workflow tree.
+ *
+ * Test Cases:
+ * 1. Immediate circular reference (depth 1): child.attachChild(parent)
+ * 2. Two-level circular reference (depth 2): grandchild.attachChild(root)
+ * 3. Three-level circular reference (depth 3): great-grandchild.attachChild(root)
+ *
+ * Pattern from: plan/docs/bugfix-architecture/implementation_patterns.md Pattern 8
+ * Related: plan/bugfix/P1M3T1S3/PRP.md
+ */
+export {};
+//# sourceMappingURL=complex-circular-reference.test.d.ts.map