groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M2T2S4/research/vitest_testing_patterns.md

@@ -1,1103 +0,0 @@
-# Vitest Testing Patterns for TypeScript Error Handling
-
-**Research Date:** 2026-01-12
-**Vitest Version:** 1.0.0
-**Project:** Groundswell - Hierarchical Workflow Orchestration Engine
-
----
-
-## Table of Contents
-
-1. [Official Vitest Documentation Resources](#official-vitest-documentation-resources)
-2. [Testing Error Aggregation Behavior](#testing-error-aggregation-behavior)
-3. [Async Error Testing Best Practices](#async-error-testing-best-practices)
-4. [Custom Error Types and Merged Errors](#custom-error-types-and-merged-errors)
-5. [Concurrent/Parallel Execution Error Scenarios](#concurrentparallel-execution-error-scenarios)
-6. [Common Gotchas and Pitfalls](#common-gotchas-and-pitfalls)
-7. [Project-Specific Testing Patterns](#project-specific-testing-patterns)
-
----
-
-## Official Vitest Documentation Resources
-
-### Core Documentation URLs
-
-- **Vitest Official Website:** https://vitest.dev/
-- **Assertions API:** https://vitest.dev/guide/assertions.html
-- **Testing TypeScript:** https://vitest.dev/guide/testing-types.html
-- **Async Testing:** https://vitest.dev/guide/async.html
-- **Mocking:** https://vitest.dev/guide/mocking.html
-- **GitHub Repository:** https://github.com/vitest-dev/vitest
-
-### Key Documentation Sections
-
-1. **Error Testing Assertions**
-   - `toThrow()` - Synchronous error testing
-   - `rejects.toThrow()` - Async error testing
-   - Custom matchers for error properties
-   - Error instance checking
-
-2. **Async Testing Patterns**
-   - Promise rejection testing
-   - Async/await patterns
-   - Timeout handling
-   - Concurrent test execution
-
----
-
-## Testing Error Aggregation Behavior
-
-### Pattern 1: Testing Error Collection and Merging
-
-**File Reference:** `/home/dustin/projects/groundswell/src/__tests__/unit/utils/workflow-error-utils.test.ts`
-
-When testing error aggregation (combining multiple errors into one), focus on:
-
-1. **Count Validation**
-2. **Unique Identification**
-3. **Context Preservation**
-4. **Metadata Structure**
-
-#### Code Example: Error Aggregation Testing
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { mergeWorkflowErrors } from '../../../utils/workflow-error-utils.js';
-import type { WorkflowError } from '../../../types/error.js';
-
-describe('mergeWorkflowErrors', () => {
-  // Helper function to create mock errors
-  function createMockWorkflowError(overrides?: Partial<WorkflowError>): WorkflowError {
-    return {
-      message: 'Test error',
-      original: new Error('Original error'),
-      workflowId: 'wf-test-123',
-      stack: 'Error: Test error\n    at test.ts:10:15',
-      state: { key: 'value' },
-      logs: [
-        {
-          id: 'log-1',
-          workflowId: 'wf-test-123',
-          timestamp: Date.now(),
-          level: 'error',
-          message: 'Test log message',
-        },
-      ],
-      ...overrides,
-    };
-  }
-
-  it('should aggregate multiple errors with unique workflow IDs', () => {
-    const error1 = createMockWorkflowError({
-      message: 'Error 1',
-      workflowId: 'wf-1',
-      stack: 'stack 1',
-      state: { key1: 'value1' },
-      logs: [{ id: 'log-1', workflowId: 'wf-1', timestamp: 1000, level: 'error', message: 'Log 1' }],
-    });
-    const error2 = createMockWorkflowError({
-      message: 'Error 2',
-      workflowId: 'wf-2',
-      stack: 'stack 2',
-      state: { key2: 'value2' },
-      logs: [{ id: 'log-2', workflowId: 'wf-2', timestamp: 2000, level: 'error', message: 'Log 2' }],
-    });
-
-    const result = mergeWorkflowErrors([error1, error2], 'concurrentTask', 'parent-wf', 5);
-
-    // Validate aggregated message
-    expect(result.message).toBe("2 of 5 concurrent child workflows failed in task 'concurrentTask'");
-    expect(result.workflowId).toBe('parent-wf');
-    expect(result.stack).toBe('stack 1'); // First error's stack
-    expect(result.state).toEqual({ key1: 'value1' }); // First error's state
-    expect(result.logs).toHaveLength(2); // All logs aggregated
-  });
-
-  it('should deduplicate workflow IDs when errors have duplicate IDs', () => {
-    const error1 = createMockWorkflowError({ workflowId: 'wf-dup' });
-    const error2 = createMockWorkflowError({ workflowId: 'wf-dup' });
-    const error3 = createMockWorkflowError({ workflowId: 'wf-unique' });
-
-    const result = mergeWorkflowErrors([error1, error2, error3], 'testTask', 'parent-wf', 4);
-
-    // Access metadata from original field
-    const metadata = result.original as {
-      failedWorkflowIds: string[];
-    };
-
-    expect(metadata.failedWorkflowIds).toEqual(['wf-dup', 'wf-unique']);
-    expect(metadata.failedWorkflowIds).toHaveLength(2); // Deduplicated
-  });
-});
-```
-
-### Best Practices for Error Aggregation Testing
-
-1. **Test Both Single and Multiple Errors**
-   ```typescript
-   it('should return a single error when merging one error', () => {
-     const error = createMockWorkflowError({ workflowId: 'wf-1' });
-     const result = mergeWorkflowErrors([error], 'testTask', 'parent-wf', 1);
-     expect(result.message).toBe("1 of 1 concurrent child workflows failed in task 'testTask'");
-   });
-   ```
-
-2. **Test Deduplication Logic**
-   - Ensure duplicate IDs are properly handled
-   - Validate unique identifier preservation
-
-3. **Test Array Flattening**
-   ```typescript
-   it('should flatten logs arrays from all errors using flatMap', () => {
-     const error1 = createMockWorkflowError({
-       workflowId: 'wf-1',
-       logs: [
-         { id: 'log-1', workflowId: 'wf-1', timestamp: 1000, level: 'info', message: 'Log 1.1' },
-         { id: 'log-2', workflowId: 'wf-1', timestamp: 2000, level: 'info', message: 'Log 1.2' },
-       ],
-     });
-     const error2 = createMockWorkflowError({
-       workflowId: 'wf-2',
-       logs: [
-         { id: 'log-3', workflowId: 'wf-2', timestamp: 3000, level: 'error', message: 'Log 2.1' },
-       ],
-     });
-
-     const result = mergeWorkflowErrors([error1, error2], 'testTask', 'parent-wf', 2);
-     expect(result.logs).toHaveLength(3);
-   });
-   ```
-
-4. **Test Metadata Preservation**
-   ```typescript
-   it('should include metadata in original field', () => {
-     const error1 = createMockWorkflowError({ workflowId: 'wf-1' });
-     const error2 = createMockWorkflowError({ workflowId: 'wf-2' });
-
-     const result = mergeWorkflowErrors([error1, error2], 'concurrentTask', 'parent-wf', 5);
-
-     const metadata = result.original as {
-       name: string;
-       message: string;
-       errors: WorkflowError[];
-       totalChildren: number;
-       failedChildren: number;
-       failedWorkflowIds: string[];
-     };
-
-     expect(metadata.name).toBe('WorkflowAggregateError');
-     expect(metadata.totalChildren).toBe(5);
-     expect(metadata.failedChildren).toBe(2);
-   });
-   ```
-
----
-
-## Async Error Testing Best Practices
-
-### Pattern 1: Using `rejects.toThrow()` for Async Errors
-
-The most common and recommended pattern for async error testing:
-
-```typescript
-import { describe, it, expect } from 'vitest';
-
-describe('async error testing', () => {
-  it('should throw error', async () => {
-    await expect(asyncFunction()).rejects.toThrow();
-    await expect(asyncFunction()).rejects.toThrow('Error message');
-    await expect(asyncFunction()).rejects.toThrow(/regex/);
-    await expect(asyncFunction()).rejects.toThrow(TypeError);
-  });
-
-  it('should throw custom error type', async () => {
-    await expect(asyncFunction()).rejects.toThrow(CustomError);
-  });
-});
-```
-
-### Pattern 2: Try-Catch with Explicit Assertions
-
-When you need to inspect error properties:
-
-```typescript
-it('should preserve error context', async () => {
-  try {
-    await asyncFunction();
-    expect.fail('Expected function to throw');
-  } catch (error) {
-    expect(error).toBeInstanceOf(Error);
-    expect(error.message).toBe('specific message');
-    if (error instanceof CustomError) {
-      expect(error.code).toBe(404);
-      expect(error.metadata).toBeDefined();
-    }
-  }
-});
-```
-
-### Pattern 3: Promise.race for Timeout Detection
-
-**File Reference:** `/home/dustin/projects/groundswell/src/__tests__/adversarial/concurrent-task-failures.test.ts`
-
-Useful for detecting hanging promises:
-
-```typescript
-it('should verify all workflows complete with no hanging promises', async () => {
-  const completedWorkflows = new Set<string>();
-
-  // Setup tracking
-  children.forEach((child) => {
-    child.run().then(
-      () => completedWorkflows.add(child.id),
-      () => completedWorkflows.add(child.id)
-    );
-  });
-
-  // ACT: Run with timeout to detect hanging promises
-  const timeoutPromise = new Promise((_, reject) =>
-    setTimeout(() => reject(new Error('Timeout: workflows hung')), 5000)
-  );
-
-  const runPromise = parent.run();
-
-  await Promise.race([runPromise, timeoutPromise]);
-
-  // ASSERT: All workflows accounted for (no orphans)
-  expect(completedWorkflows.size).toBe(10);
-});
-```
-
-### Pattern 4: Testing Expected Errors with try-catch
-
-**From the project's concurrent test patterns:**
-
-```typescript
-class ParentWorkflow extends Workflow {
-  @Task({ concurrent: true })
-  async spawnChildren() {
-    return [
-      createChildWorkflow(this, 'Child-0', false),
-      createChildWorkflow(this, 'Child-1', true), // Will fail
-      createChildWorkflow(this, 'Child-2', false),
-    ];
-  }
-
-  async run() {
-    try {
-      await this.spawnChildren();
-    } catch (err) {
-      // Expected - first error thrown after all complete
-      return err;
-    }
-  }
-}
-
-const parent = new ParentWorkflow('Parent');
-const thrownError = await parent.run();
-
-// ASSERT: Error was thrown
-expect(thrownError).toBeDefined();
-expect((thrownError as any).message).toContain('Child-1 failed');
-```
-
-### Key Best Practices for Async Error Testing
-
-1. **Always use `await` with `rejects.toThrow()`**
-   ```typescript
-   // BAD
-   expect(asyncFunction()).rejects.toThrow();
-
-   // GOOD
-   await expect(asyncFunction()).rejects.toThrow();
-   ```
-
-2. **Test error messages for specificity**
-   ```typescript
-   await expect(asyncFunction()).rejects.toThrow('specific error message');
-   await expect(asyncFunction()).rejects.toThrow(/error pattern/);
-   ```
-
-3. **Test error types when specific errors matter**
-   ```typescript
-   await expect(asyncFunction()).rejects.toThrow(TypeError);
-   await expect(asyncFunction()).rejects.toThrow(CustomError);
-   ```
-
-4. **Use `expect.fail()` for unexpected success**
-   ```typescript
-   it('should throw error', async () => {
-     try {
-       await asyncFunction();
-       expect.fail('Expected function to throw');
-     } catch (error) {
-       expect(error).toBeInstanceOf(Error);
-     }
-   });
-   ```
-
-5. **Handle expected errors gracefully**
-   ```typescript
-   async run() {
-     try {
-       await this.spawnChildren();
-     } catch (err) {
-       // Expected - continue with validation
-       return err;
-     }
-   }
-   ```
-
----
-
-## Custom Error Types and Merged Errors
-
-### Pattern 1: Custom Error Instance Testing
-
-```typescript
-class WorkflowAggregateError extends Error {
-  constructor(
-    public errors: Error[],
-    public failedWorkflowIds: string[],
-    public totalChildren: number,
-    public failedChildren: number
-  ) {
-    super('Aggregate error');
-    this.name = 'WorkflowAggregateError';
-  }
-}
-
-describe('custom error types', () => {
-  it('should throw and identify custom error', async () => {
-    await expect(asyncFunction()).rejects.toThrow(WorkflowAggregateError);
-  });
-
-  it('should validate custom error properties', async () => {
-    try {
-      await asyncFunction();
-      expect.fail('Expected WorkflowAggregateError');
-    } catch (error) {
-      expect(error).toBeInstanceOf(WorkflowAggregateError);
-      if (error instanceof WorkflowAggregateError) {
-        expect(error.errors).toHaveLength(3);
-        expect(error.failedWorkflowIds).toContain('wf-1');
-        expect(error.totalChildren).toBe(5);
-        expect(error.failedChildren).toBe(3);
-      }
-    }
-  });
-});
-```
-
-### Pattern 2: Testing Wrapped/Merged Errors
-
-**Project Pattern from workflow-error-utils.test.ts:**
-
-```typescript
-it('should include metadata in original field', () => {
-  const error1 = createMockWorkflowError({ workflowId: 'wf-1' });
-  const error2 = createMockWorkflowError({ workflowId: 'wf-2' });
-
-  const result = mergeWorkflowErrors([error1, error2], 'concurrentTask', 'parent-wf', 5);
-
-  // Access wrapped metadata from original field
-  const metadata = result.original as {
-    name: string;
-    message: string;
-    errors: WorkflowError[];
-    totalChildren: number;
-    failedChildren: number;
-    failedWorkflowIds: string[];
-  };
-
-  expect(metadata.name).toBe('WorkflowAggregateError');
-  expect(metadata.errors).toEqual([error1, error2]);
-  expect(metadata.totalChildren).toBe(5);
-  expect(metadata.failedChildren).toBe(2);
-  expect(metadata.failedWorkflowIds).toEqual(['wf-1', 'wf-2']);
-});
-```
-
-### Pattern 3: Error Property Validation with `expect.objectContaining`
-
-```typescript
-it('should validate error structure without type assertion', () => {
-  expect(() => throwError()).toThrow(
-    expect.objectContaining({
-      message: 'Error message',
-      code: 'ERROR_CODE',
-      workflowId: expect.any(String),
-    })
-  );
-});
-```
-
-### Pattern 4: Testing Error State Preservation
-
-```typescript
-it('should use first error state', () => {
-  const error1 = createMockWorkflowError({ state: { first: 'state1' } });
-  const error2 = createMockWorkflowError({ state: { second: 'state2' } });
-
-  const result = mergeWorkflowErrors([error1, error2], 'testTask', 'parent-wf', 2);
-
-  expect(result.state).toEqual({ first: 'state1' });
-});
-
-it('should handle undefined state gracefully', () => {
-  const error1 = createMockWorkflowError({ state: undefined as any });
-  const error2 = createMockWorkflowError({ state: { hasState: 'yes' } });
-
-  const result = mergeWorkflowErrors([error1, error2], 'testTask', 'parent-wf', 2);
-
-  expect(result.state).toEqual({});
-});
-```
-
----
-
-## Concurrent/Parallel Execution Error Scenarios
-
-### Pattern 1: Testing Promise.allSettled Behavior
-
-**File Reference:** `/home/dustin/projects/groundswell/src/__tests__/adversarial/concurrent-task-failures.test.ts`
-
-Key pattern: Ensure all operations complete despite failures:
-
-```typescript
-describe('Single child failure scenarios', () => {
-  it('should complete all siblings when one child fails', async () => {
-    // ARRANGE: Create parent with 4 children, child[1] will fail
-    class ParentWorkflow extends Workflow {
-      @Task({ concurrent: true })
-      async spawnChildren() {
-        return [
-          createChildWorkflow(this, 'Child-0', false),
-          createChildWorkflow(this, 'Child-1', true), // Will fail
-          createChildWorkflow(this, 'Child-2', false),
-          createChildWorkflow(this, 'Child-3', false),
-        ];
-      }
-
-      async run() {
-        try {
-          await this.spawnChildren();
-        } catch (err) {
-          // Expected - first error thrown after all complete
-        }
-      }
-    }
-
-    const parent = new ParentWorkflow('Parent');
-
-    // ACT: Run parent (children run concurrently)
-    await parent.run();
-
-    // ASSERT: All 4 children attached (Promise.allSettled completed all)
-    expect(parent.children.length).toBe(4);
-
-    // ASSERT: Verify child names match what we created
-    const childNames = parent.children.map((c) => (c as any).node.name);
-    expect(childNames).toContain('Child-0');
-    expect(childNames).toContain('Child-1');
-    expect(childNames).toContain('Child-2');
-    expect(childNames).toContain('Child-3');
-  });
-});
-```
-
-### Pattern 2: Testing Multiple Concurrent Failures
-
-```typescript
-describe('Multiple concurrent failures', () => {
-  it('should collect all errors when multiple children fail concurrently', async () => {
-    // ARRANGE: Create parent with 6 children, 3 will fail
-    class ParentWorkflow extends Workflow {
-      @Task({ concurrent: true })
-      async spawnChildren() {
-        return [
-          createChildWorkflow(this, 'Alpha', false),
-          createChildWorkflow(this, 'Beta', true), // Will fail
-          createChildWorkflow(this, 'Gamma', false),
-          createChildWorkflow(this, 'Delta', true), // Will fail
-          createChildWorkflow(this, 'Epsilon', false),
-          createChildWorkflow(this, 'Zeta', true), // Will fail
-        ];
-      }
-
-      async run() {
-        try {
-          await this.spawnChildren();
-        } catch (err) {
-          // Expected
-        }
-      }
-    }
-
-    const parent = new ParentWorkflow('Parent');
-    await parent.run();
-
-    // ASSERT: All 6 children attached (Promise.allSettled completed all)
-    expect(parent.children.length).toBe(6);
-  });
-});
-```
-
-### Pattern 3: Event Emission Verification
-
-```typescript
-function setupEventObserver(workflow: Workflow): WorkflowEvent[] {
-  const events: WorkflowEvent[] = [];
-  workflow.addObserver({
-    onLog: () => {},
-    onEvent: (e) => events.push(e),
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  });
-  return events;
-}
-
-it('should emit error events for all failing workflows', async () => {
-  class ParentWorkflow extends Workflow {
-    @Task({ concurrent: true })
-    async spawnChildren() {
-      return [
-        createChildWorkflow(this, 'Good', false),
-        createChildWorkflow(this, 'Bad1', true),
-        createChildWorkflow(this, 'Bad2', true),
-      ];
-    }
-
-    async run() {
-      try {
-        await this.spawnChildren();
-      } catch (err) {
-        // Expected
-      }
-    }
-  }
-
-  const parent = new ParentWorkflow('Parent');
-  const events: WorkflowEvent[] = [];
-
-  // CRITICAL: Add observer to root workflow
-  parent.addObserver({
-    onLog: () => {},
-    onEvent: (e) => events.push(e),
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  });
-
-  await parent.run();
-
-  // ASSERT: Error events emitted for both failures
-  const errorEvents = events.filter((e) => e.type === 'error');
-  expect(errorEvents.length).toBeGreaterThanOrEqual(2);
-
-  // ASSERT: Each error event has correct structure
-  errorEvents.forEach((event) => {
-    expect(event.type).toBe('error');
-    if (event.type === 'error') {
-      expect(event.error).toBeDefined();
-      expect(event.error.workflowId).toBeDefined();
-      expect(event.error.message).toBeDefined();
-      expect(Array.isArray(event.error.logs)).toBe(true);
-    }
-  });
-});
-```
-
-### Pattern 4: Completion Tracking (No Orphaned Promises)
-
-```typescript
-it('should ensure no orphaned workflows in mixed scenario', async () => {
-  // ARRANGE: Track all completions
-  const completedWorkflows = new Set<string>();
-
-  class ParentWorkflow extends Workflow {
-    @Task({ concurrent: true })
-    async spawnChildren() {
-      const children = [
-        createChildWorkflow(this, 'Alpha', false),
-        createChildWorkflow(this, 'Beta', true),
-        createChildWorkflow(this, 'Gamma', false),
-      ];
-
-      // Track completion for all children
-      children.forEach((child) => {
-        child.run().then(
-          () => completedWorkflows.add(child.id),
-          () => completedWorkflows.add(child.id)
-        );
-      });
-
-      return children;
-    }
-
-    async run() {
-      try {
-        await this.spawnChildren();
-      } catch (err) {
-        // Expected
-      }
-    }
-  }
-
-  const parent = new ParentWorkflow('Parent');
-  await parent.run();
-
-  // ASSERT: All workflows accounted for (no orphans)
-  expect(completedWorkflows.size).toBe(3);
-  expect(parent.children.length).toBe(3);
-});
-```
-
-### Pattern 5: Log Capture from Concurrent Operations
-
-```typescript
-it('should capture logs from both successful and failed workflows', async () => {
-  class ChildWorkflow extends Workflow {
-    private shouldFail: boolean;
-
-    constructor(name: string, parent: Workflow, shouldFail: boolean) {
-      super(name, parent);
-      this.shouldFail = shouldFail;
-    }
-
-    @Step()
-    async executeStep() {
-      this.logger.info(`${this.node.name} is running`);
-      if (this.shouldFail) {
-        this.logger.error(`${this.node.name} is about to fail`);
-        throw new Error(`${this.node.name} failed`);
-      }
-      this.logger.info(`${this.node.name} completed successfully`);
-      return `${this.node.name} succeeded`;
-    }
-
-    async run() {
-      return this.executeStep();
-    }
-  }
-
-  class ParentWorkflow extends Workflow {
-    @Task({ concurrent: true })
-    async spawnChildren() {
-      return [
-        new ChildWorkflow('SuccessChild', this, false),
-        new ChildWorkflow('FailChild', this, true),
-      ];
-    }
-
-    async run() {
-      try {
-        await this.spawnChildren();
-      } catch (err) {
-        // Expected
-      }
-    }
-  }
-
-  const parent = new ParentWorkflow('Parent');
-  const allLogs: string[] = [];
-
-  parent.addObserver({
-    onLog: (entry) => allLogs.push(entry.message),
-    onEvent: () => {},
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  });
-
-  await parent.run();
-
-  // ASSERT: Logs from both children captured
-  expect(allLogs.some((msg) => msg.includes('SuccessChild is running'))).toBe(true);
-  expect(allLogs.some((msg) => msg.includes('FailChild is about to fail'))).toBe(true);
-});
-```
-
----
-
-## Common Gotchas and Pitfalls
-
-### Gotcha 1: Forgetting `await` with `rejects.toThrow()`
-
-```typescript
-// BAD - Test will pass even if function doesn't throw
-it('bad example', () => {
-  expect(asyncFunction()).rejects.toThrow();
-});
-
-// GOOD
-it('good example', async () => {
-  await expect(asyncFunction()).rejects.toThrow();
-});
-```
-
-### Gotcha 2: Not Handling Expected Errors
-
-```typescript
-// BAD - Test will fail due to unhandled error
-it('bad example', async () => {
-  await expect(asyncFunction()).rejects.toThrow();
-  await expect(anotherAsyncFunction()).rejects.toThrow(); // Never runs if first throws
-});
-
-// GOOD - Handle expected errors
-it('good example', async () => {
-  try {
-    await asyncFunction();
-  } catch (err) {
-    // Expected
-  }
-  await expect(anotherAsyncFunction()).rejects.toThrow();
-});
-```
-
-### Gotcha 3: Race Conditions in Concurrent Tests
-
-```typescript
-// BAD - Non-deterministic results
-it('bad example', async () => {
-  const promises = [asyncFn1(), asyncFn2(), asyncFn3()];
-  await Promise.all(promises);
-  // May fail if promises complete in different order
-});
-
-// GOOD - Use Promise.allSettled and track completion
-it('good example', async () => {
-  const completed = new Set<string>();
-  const promises = [
-    asyncFn1().finally(() => completed.add('fn1')),
-    asyncFn2().finally(() => completed.add('fn2')),
-    asyncFn3().finally(() => completed.add('fn3')),
-  ];
-  await Promise.allSettled(promises);
-  expect(completed.size).toBe(3);
-});
-```
-
-### Gotcha 4: Type Assertions Without Guards
-
-```typescript
-// BAD - Unsafe type assertion
-it('bad example', async () => {
-  try {
-    await asyncFunction();
-  } catch (error) {
-    expect((error as CustomError).code).toBe(404); // May crash if not CustomError
-  }
-});
-
-// GOOD - Use type guards
-it('good example', async () => {
-  try {
-    await asyncFunction();
-  } catch (error) {
-    expect(error).toBeInstanceOf(CustomError);
-    if (error instanceof CustomError) {
-      expect(error.code).toBe(404);
-    }
-  }
-});
-```
-
-### Gotcha 5: Not Testing All Concurrent Scenarios
-
-```typescript
-// BAD - Only tests failure case
-it('bad example', async () => {
-  await expect(failingTask()).rejects.toThrow();
-});
-
-// GOOD - Test all scenarios: all fail, some fail, none fail
-describe('concurrent task scenarios', () => {
-  it('should handle all failing', async () => { /* ... */ });
-  it('should handle some failing', async () => { /* ... */ });
-  it('should handle none failing', async () => { /* ... */ });
-});
-```
-
-### Gotcha 6: Hanging Promises in Concurrent Tests
-
-```typescript
-// BAD - Test may hang indefinitely
-it('bad example', async () => {
-  const promises = [asyncFn1(), asyncFn2()];
-  // If one hangs, test never completes
-  await Promise.all(promises);
-});
-
-// GOOD - Use timeout
-it('good example', async () => {
-  const timeoutPromise = new Promise((_, reject) =>
-    setTimeout(() => reject(new Error('Timeout')), 5000)
-  );
-
-  const runPromise = Promise.all([asyncFn1(), asyncFn2()]);
-  await Promise.race([runPromise, timeoutPromise]);
-});
-```
-
-### Gotcha 7: Not Verifying Error Properties
-
-```typescript
-// BAD - Only checks that error was thrown
-it('bad example', async () => {
-  await expect(asyncFunction()).rejects.toThrow();
-});
-
-// GOOD - Verify error structure
-it('good example', async () => {
-  await expect(asyncFunction()).rejects.toThrow(expect.objectContaining({
-    message: 'specific message',
-    code: 'SPECIFIC_ERROR',
-    workflowId: expect.any(String),
-  }));
-});
-```
-
-### Gotcha 8: Missing Observer Setup for Event Testing
-
-```typescript
-// BAD - Events won't be captured
-it('bad example', async () => {
-  const parent = new ParentWorkflow('Parent');
-  await parent.run();
-  expect(events.length).toBe(0); // Events array doesn't exist!
-});
-
-// GOOD - Setup observer before execution
-it('good example', async () => {
-  const parent = new ParentWorkflow('Parent');
-  const events: WorkflowEvent[] = [];
-
-  // CRITICAL: Add observer BEFORE running
-  parent.addObserver({
-    onLog: () => {},
-    onEvent: (e) => events.push(e),
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  });
-
-  await parent.run();
-  expect(events.length).toBeGreaterThan(0);
-});
-```
-
----
-
-## Project-Specific Testing Patterns
-
-### Pattern 1: Helper Functions for Test Data Creation
-
-**From workflow-error-utils.test.ts:**
-
-```typescript
-function createMockWorkflowError(overrides?: Partial<WorkflowError>): WorkflowError {
-  return {
-    message: 'Test error',
-    original: new Error('Original error'),
-    workflowId: 'wf-test-123',
-    stack: 'Error: Test error\n    at test.ts:10:15',
-    state: { key: 'value' },
-    logs: [
-      {
-        id: 'log-1',
-        workflowId: 'wf-test-123',
-        timestamp: Date.now(),
-        level: 'error',
-        message: 'Test log message',
-      },
-    ],
-    ...overrides,
-  };
-}
-```
-
-### Pattern 2: Deterministic Child Workflow Creation
-
-**From concurrent-task-failures.test.ts:**
-
-```typescript
-function createChildWorkflow(
-  parent: Workflow,
-  name: string,
-  shouldFail: boolean = false
-): Workflow {
-  return new (class extends Workflow {
-    constructor(n: string, p: Workflow) {
-      super(n, p);
-    }
-
-    @Step()
-    async executeStep() {
-      if (shouldFail) {
-        throw new Error(`${name} failed`);
-      }
-      return `${name} succeeded`;
-    }
-
-    async run() {
-      return this.executeStep();
-    }
-  })(name, parent);
-}
-```
-
-### Pattern 3: Event Observer Setup Pattern
-
-```typescript
-function setupEventObserver(workflow: Workflow): WorkflowEvent[] {
-  const events: WorkflowEvent[] = [];
-  workflow.addObserver({
-    onLog: () => {},
-    onEvent: (e) => events.push(e),
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  });
-  return events;
-}
-```
-
-### Pattern 4: Comprehensive Test Organization
-
-**From concurrent-task-failures.test.ts:**
-
-```typescript
-describe('@Task decorator concurrent failure scenarios', () => {
-  describe('Single child failure scenarios', () => {
-    it('should complete all siblings when one child fails', async () => {
-      // ARRANGE: Create parent with 4 children, child[1] will fail
-      // ACT: Run parent (children run concurrently)
-      // ASSERT: All 4 children attached (Promise.allSettled completed all)
-    });
-  });
-
-  describe('Multiple concurrent failures', () => {
-    it('should collect all errors when multiple children fail concurrently', async () => {
-      // ...
-    });
-  });
-
-  describe('Mixed success/failure scenarios', () => {
-    it('should complete successful workflows despite failures', async () => {
-      // ...
-    });
-  });
-
-  describe('All children failing', () => {
-    it('should handle edge case of all children failing', async () => {
-      // ...
-    });
-  });
-
-  describe('No orphaned workflows', () => {
-    it('should verify all workflows complete with no hanging promises', async () => {
-      // ...
-    });
-  });
-
-  describe('Event emission verification', () => {
-    it('should emit error events for all failing workflows', async () => {
-      // ...
-    });
-  });
-});
-```
-
----
-
-## Summary of Key Testing Patterns
-
-### For Error Aggregation:
-1. Test single error case (edge case)
-2. Test multiple error aggregation
-3. Test deduplication of IDs
-4. Test array flattening (logs, etc.)
-5. Test metadata preservation in wrapped errors
-6. Test state/stack selection strategies (first error wins)
-
-### For Async Errors:
-1. Use `await expect().rejects.toThrow()` for basic cases
-2. Use try-catch for detailed error inspection
-3. Use `expect.fail()` for unexpected success
-4. Test error messages with string or regex
-5. Test error types with constructors
-6. Handle expected errors gracefully
-
-### For Custom Errors:
-1. Test with `toBeInstanceOf()` and custom error class
-2. Use type guards before accessing custom properties
-3. Test wrapped error metadata through `original` field
-4. Use `expect.objectContaining()` for partial matching
-5. Test state preservation and handling of undefined values
-
-### For Concurrent Execution:
-1. Test all scenarios: all fail, some fail, none fail
-2. Use `Promise.allSettled()` patterns for completion verification
-3. Track completion with Sets to detect orphaned operations
-4. Setup event observers before execution
-5. Use timeouts to detect hanging promises
-6. Verify logs from both successful and failed operations
-
-### Common Pitfalls to Avoid:
-1. Forgetting `await` with `rejects.toThrow()`
-2. Not handling expected errors in test flow
-3. Race conditions from improper promise handling
-4. Unsafe type assertions without guards
-5. Not testing all concurrent scenarios
-6. Hanging promises from missing timeouts
-7. Not verifying error properties thoroughly
-8. Missing observer setup for event testing
-
----
-
-## Additional Resources
-
-### Project Test Files Referenced:
-- `/home/dustin/projects/groundswell/src/__tests__/unit/utils/workflow-error-utils.test.ts`
-- `/home/dustin/projects/groundswell/src/__tests__/adversarial/concurrent-task-failures.test.ts`
-
-### Related Types:
-- `/home/dustin/projects/groundswell/src/types/error.ts` - WorkflowError interface
-
-### Configuration:
-- `/home/dustin/projects/groundswell/vitest.config.ts` - Test configuration
-- `/home/dustin/projects/groundswell/package.json` - Dependencies and scripts
-
----
-
-## Quick Reference: Vitest Error Testing Assertions
-
-```typescript
-// Synchronous errors
-expect(() => syncFunction()).toThrow()
-expect(() => syncFunction()).toThrow(Error)
-expect(() => syncFunction()).toThrow('message')
-expect(() => syncFunction()).toThrow(/regex/)
-expect(() => syncFunction()).toThrow(CustomError)
-
-// Async errors
-await expect(asyncFunction()).rejects.toThrow()
-await expect(asyncFunction()).rejects.toThrow(Error)
-await expect(asyncFunction()).rejects.toThrow('message')
-await expect(asyncFunction()).rejects.toThrow(/regex/)
-await expect(asyncFunction()).rejects.toThrow(CustomError)
-
-// Error property matching
-expect(() => throwError()).toThrow(
-  expect.objectContaining({
-    message: 'specific',
-    code: 'CODE',
-  })
-)
-
-// Instance checking
-expect(error).toBeInstanceOf(Error)
-expect(error).toBeInstanceOf(CustomError)
-```
-
----
-
-*End of Research Report*