groundswell 0.0.1 → 0.0.2

package/src/core/workflow.ts

@@ -3,6 +3,7 @@ import type {
   WorkflowStatus,
   WorkflowEvent,
   WorkflowObserver,
+  LogEntry,
 } from '../types/index.js';
 import type { WorkflowContext, WorkflowConfig, WorkflowResult } from '../types/workflow-context.js';
 import { generateId } from '../utils/id.js';
@@ -57,7 +58,7 @@ export class Workflow<T = unknown> {
   protected readonly logger: WorkflowLogger;
 
   /** The node representation of this workflow */
-  protected readonly node: WorkflowNode;
+  public readonly node: WorkflowNode;
 
   /** Observers (only populated on root workflow) */
   private observers: WorkflowObserver[] = [];
@@ -94,6 +95,17 @@ export class Workflow<T = unknown> {
       this.parent = (parentOrExecutor as Workflow) ?? null;
     }
 
+    // Validate workflow name (after config is normalized)
+    if (typeof this.config.name === 'string') {
+      const trimmedName = this.config.name.trim();
+      if (trimmedName.length === 0) {
+        throw new Error('Workflow name cannot be empty or whitespace only');
+      }
+      if (this.config.name.length > 100) {
+        throw new Error('Workflow name cannot exceed 100 characters');
+      }
+    }
+
     // Create the node representation
     this.node = {
       id: this.id,
@@ -118,22 +130,113 @@ export class Workflow<T = unknown> {
   /**
    * Get observers from the root workflow
    * Traverses up the tree to find the root
+   * Uses cycle detection to prevent infinite loops from circular parent-child relationships
    */
   private getRootObservers(): WorkflowObserver[] {
-    if (this.parent) {
-      return this.parent.getRootObservers();
+    const visited = new Set<Workflow>();
+    let root: Workflow = this;
+    let current: Workflow | null = this;
+
+    while (current) {
+      if (visited.has(current)) {
+        throw new Error('Circular parent-child relationship detected');
+      }
+      visited.add(current);
+      root = current;
+      current = current.parent;
+    }
+
+    return root.observers;
+  }
+
+  /**
+   * Check if this workflow is a descendant of the given ancestor workflow.
+   *
+   * Traverses the parent chain upward looking for the ancestor reference.
+   * Uses a visited Set to detect cycles during traversal. This method provides
+   * a convenient way to check workflow hierarchy relationships without manually
+   * traversing the parent chain.
+   *
+   * @warning This method reveals workflow hierarchy information. If your
+   * application exposes workflows via an API, ensure you implement proper
+   * access control to prevent unauthorized topology discovery. Note that
+   * the `parent` and `children` properties are already public, so this
+   * method does not expose any new information beyond what is currently
+   * accessible.
+   *
+   * **Time Complexity**: O(d) where d is the depth of the hierarchy
+   * **Space Complexity**: O(d) for the visited Set in worst case (cycle detection)
+   *
+   * @example Check if a workflow belongs to a specific hierarchy
+   * ```typescript
+   * const root = new Workflow('root');
+   * const child = new Workflow('child', { parent: root });
+   *
+   * if (child.isDescendantOf(root)) {
+   *   console.log('Child is in root hierarchy');
+   * }
+   * ```
+   *
+   * @example Validate before attaching to prevent circular references
+   * ```typescript
+   * if (!newChild.isDescendantOf(parent)) {
+   *   parent.attachChild(newChild);
+   * } else {
+   *   throw new Error('Would create circular reference');
+   * }
+   * ```
+   *
+   * @example Check for ancestor relationship in conditional logic
+   * ```typescript
+   * const isInProductionBranch = workflow.isDescendantOf(productionRoot);
+   * if (isInProductionBranch) {
+   *   // Apply production-specific logic
+   * }
+   * ```
+   *
+   * @param ancestor - The potential ancestor workflow to check
+   * @returns true if ancestor is found in parent chain, false otherwise
+   * @throws {Error} If a cycle is detected during traversal (indicates corrupted tree structure)
+   */
+  public isDescendantOf(ancestor: Workflow): boolean {
+    const visited = new Set<Workflow>();
+    let current: Workflow | null = this.parent;
+
+    while (current !== null) {
+      if (visited.has(current)) {
+        throw new Error('Circular parent-child relationship detected');
+      }
+      visited.add(current);
+
+      if (current === ancestor) {
+        return true;
+      }
+
+      current = current.parent;
     }
-    return this.observers;
+
+    return false;
   }
 
   /**
    * Get the root workflow
+   * Uses cycle detection to prevent infinite loops from circular parent-child relationships
    */
   protected getRoot(): Workflow {
-    if (this.parent) {
-      return this.parent.getRoot();
+    const visited = new Set<Workflow>();
+    let root: Workflow = this;
+    let current: Workflow | null = this;
+
+    while (current) {
+      if (visited.has(current)) {
+        throw new Error('Circular parent-child relationship detected');
+      }
+      visited.add(current);
+      root = current;
+      current = current.parent;
     }
-    return this;
+
+    return root;
   }
 
   /**
@@ -158,10 +261,88 @@ export class Workflow<T = unknown> {
   }
 
   /**
-   * Attach a child workflow
-   * Called automatically in constructor when parent is provided
+   * Attach a child workflow to this parent workflow.
+   *
+   * Validates that the child can be attached by checking:
+   * 1. Child is not already attached to this parent workflow
+   * 2. Child does not have a different parent (enforces single-parent invariant)
+   * 3. Child is not an ancestor of this parent (prevents circular references)
+   *
+   * **Structural Changes:**
+   * - Adds child to this.children array (workflow tree)
+   * - Adds child.node to this.node.children array (node tree)
+   * - Sets child.parent = this (workflow tree)
+   * - Sets child.node.parent = this.node (node tree)
+   * - Emits childAttached event to notify observers
+   *
+   * **Invariants Maintained:**
+   * - Single-parent rule: A workflow can only have one parent
+   * - 1:1 tree mirror: workflow tree and node tree stay synchronized
+   * - No cycles: A workflow cannot be its own ancestor
+   *
+   * **Cycle Detection:**
+   * - Uses isDescendantOf() helper with Set-based cycle detection
+   * - Throws immediately if circular reference would be created
+   *
+   * @param child - The child workflow to attach
+   * @throws {Error} If the child is already attached to this workflow
+   * @throws {Error} If the child already has a different parent (use detachChild() first for reparenting)
+   * @throws {Error} If the child is an ancestor of this parent (would create circular reference)
+   *
+   * @example
+   * ```ts
+   * const parent = new Workflow('Parent');
+   * const child = new Workflow('Child');
+   * parent.attachChild(child);
+   * // child.parent === parent
+   * // parent.children.includes(child) === true
+   * ```
+   *
+   * @example Reparenting workflow
+   * ```ts
+   * const parent1 = new Workflow('Parent1');
+   * const parent2 = new Workflow('Parent2');
+   * const child = new Workflow('Child', parent1); // Attached to parent1
+   *
+   * // Later, move child to parent2
+   * parent1.detachChild(child);
+   * parent2.attachChild(child);
+   * // child.parent === parent2
+   * ```
+   *
+   * @see detachChild - For detaching children (enables reparenting)
+   * @see isDescendantOf - Private helper for circular reference detection
    */
   public attachChild(child: Workflow): void {
+    if (this.children.includes(child)) {
+      throw new Error('Child already attached to this workflow');
+    }
+
+    // Check if child already has a different parent
+    if (child.parent !== null && child.parent !== this) {
+      const errorMessage =
+        `Child '${child.node.name}' already has a parent '${child.parent.node.name}'. ` +
+        `A workflow can only have one parent. ` +
+        `Use detachChild() on '${child.parent.node.name}' first if you need to reparent.`;
+      console.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+
+    // Check if child is an ancestor (would create circular reference)
+    if (this.isDescendantOf(child)) {
+      const errorMessage =
+        `Cannot attach child '${child.node.name}' - it is an ancestor of '${this.node.name}'. ` +
+        `This would create a circular reference.`;
+      console.error(errorMessage);
+      throw new Error(errorMessage);
+    }
+
+    // Update child's parent if it's currently null
+    if (child.parent === null) {
+      child.parent = this;
+      child.node.parent = this.node; // Maintain 1:1 mirror between workflow tree and node tree
+    }
+
     this.children.push(child);
     this.node.children.push(child.node);
 
@@ -173,6 +354,59 @@ export class Workflow<T = unknown> {
     });
   }
 
+  /**
+   * Detach a child workflow from this parent workflow.
+   *
+   * Removes the child from both the workflow tree (this.children) and
+   * the node tree (this.node.children), clears the child's parent reference,
+   * and emits a childDetached event to notify observers.
+   *
+   * This enables reparenting workflows: oldParent.detachChild(child); newParent.attachChild(child);
+   *
+   * @param child - The child workflow to detach
+   * @throws {Error} If the child is not attached to this parent workflow
+   *
+   * @example
+   * ```ts
+   * const parent = new Workflow('Parent');
+   * const child = new Workflow('Child', parent);
+   *
+   * // Later, reparent to a different parent
+   * parent.detachChild(child);
+   * newParent.attachChild(child);
+   * ```
+   */
+  public detachChild(child: Workflow): void {
+    // Validate child is actually attached
+    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 tree (this.children array)
+    this.children.splice(index, 1);
+
+    // Remove from node tree (this.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 (both workflow tree and node tree)
+    child.parent = null;
+    child.node.parent = null; // Maintain 1:1 mirror between workflow tree and node tree
+
+    // Emit childDetached event
+    this.emitEvent({
+      type: 'childDetached',
+      parentId: this.id,
+      childId: child.id,
+    });
+  }
+
   /**
    * Emit an event to all root observers
    */
@@ -185,11 +419,11 @@ export class Workflow<T = unknown> {
         obs.onEvent(event);
 
         // Also notify tree changed for tree update events
-        if (event.type === 'treeUpdated' || event.type === 'childAttached') {
+        if (event.type === 'treeUpdated' || event.type === 'childAttached' || event.type === 'childDetached') {
           obs.onTreeChanged(this.getRoot().node);
         }
       } catch (err) {
-        console.error('Observer onEvent error:', err);
+        this.logger.error('Observer onEvent error', { error: err, eventType: event.type });
       }
     }
   }
@@ -207,7 +441,7 @@ export class Workflow<T = unknown> {
       try {
         obs.onStateUpdated(this.node);
       } catch (err) {
-        console.error('Observer onStateUpdated error:', err);
+        this.logger.error('Observer onStateUpdated error', { error: err, nodeId: this.node.id });
       }
     }
 
@@ -216,6 +450,9 @@ export class Workflow<T = unknown> {
       type: 'stateSnapshot',
       node: this.node,
     });
+
+    // Emit treeUpdated event to trigger tree debugger rebuild
+    this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
   }
 
   /**
@@ -224,6 +461,7 @@ export class Workflow<T = unknown> {
   public setStatus(status: WorkflowStatus): void {
     this.status = status;
     this.node.status = status;
+    this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
   }
 
   /**
@@ -291,8 +529,8 @@ export class Workflow<T = unknown> {
           original: error,
           workflowId: this.id,
           stack: error instanceof Error ? error.stack : undefined,
-          state: {},
-          logs: [],
+          state: getObservedState(this),
+          logs: [...this.node.logs] as LogEntry[],
         },
       });
 

package/src/debugger/tree-debugger.ts

@@ -57,6 +57,32 @@ export class WorkflowTreeDebugger implements WorkflowObserver {
     }
   }
 
+  /**
+   * Remove entire subtree from node map using BFS traversal
+   * O(k) complexity where k = number of nodes in subtree
+   * Uses iterative BFS to avoid stack overflow on deep trees
+   */
+  private removeSubtreeNodes(nodeId: string): void {
+    const node = this.nodeMap.get(nodeId);
+    if (!node) return;  // Already removed or never existed
+
+    // BFS traversal to collect all descendant IDs
+    const toRemove: string[] = [];
+    const queue: WorkflowNode[] = [node];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      toRemove.push(current.id);
+      // Add children to queue for BFS traversal
+      queue.push(...current.children);
+    }
+
+    // Batch delete all collected keys (atomic update)
+    for (const id of toRemove) {
+      this.nodeMap.delete(id);
+    }
+  }
+
   // WorkflowObserver implementation
 
   onLog(_entry: LogEntry): void {
@@ -64,12 +90,29 @@ export class WorkflowTreeDebugger implements WorkflowObserver {
   }
 
   onEvent(event: WorkflowEvent): void {
-    // Rebuild node map on structural changes
-    if (event.type === 'childAttached') {
-      this.buildNodeMap(event.child);
+    // Handle structural events with incremental updates
+    switch (event.type) {
+      case 'childAttached':
+        // Keep existing logic - already optimal O(k)
+        this.buildNodeMap(event.child);
+        break;
+
+      case 'childDetached':
+        // NEW: Incremental subtree removal
+        this.removeSubtreeNodes(event.childId);
+        break;
+
+      case 'treeUpdated':
+        // NEW: Update root reference only
+        this.root = event.root;
+        break;
+
+      default:
+        // Non-structural events - no map update needed
+        break;
     }
 
-    // Forward to event stream
+    // Always forward to event stream (existing behavior)
     this.events.next(event);
   }
 
@@ -78,9 +121,11 @@ export class WorkflowTreeDebugger implements WorkflowObserver {
   }
 
   onTreeChanged(root: WorkflowNode): void {
-    this.root = root;
-    this.nodeMap.clear();
-    this.buildNodeMap(root);
+    // All tree changes now handled incrementally in onEvent()
+    // Just update root reference if different
+    if (this.root !== root) {
+      this.root = root;
+    }
   }
 
   // Public API

package/src/decorators/task.ts

@@ -1,4 +1,5 @@
-import type { TaskOptions, WorkflowNode, WorkflowEvent } from '../types/index.js';
+import type { TaskOptions, WorkflowNode, WorkflowEvent, WorkflowError, SerializedWorkflowState } from '../types/index.js';
+import { mergeWorkflowErrors } from '../utils/workflow-error-utils.js';
 
 // Type for workflow-like objects
 interface WorkflowLike {
@@ -29,6 +30,38 @@ interface WorkflowClass {
  *     ];
  *   }
  * }
+ *
+ * @example Non-workflow return (silently skipped)
+ * class MyWorkflow extends Workflow {
+ *   @Task()
+ *   async returnsString(): Promise<string> {
+ *     return 'not a workflow';  // Returned as-is, not attached
+ *   }
+ * }
+ *
+ * @example Mixed return (only workflows attached)
+ * class MyWorkflow extends Workflow {
+ *   @Task()
+ *   async mixedReturn(): Promise<(Workflow | string)[]> {
+ *     return [
+ *       new ChildWorkflow('child1', this),  // Attached
+ *       'some string',                       // Skipped
+ *       new ChildWorkflow('child2', this),  // Attached
+ *     ];
+ *   }
+ * }
+ *
+ * Validation Behavior
+ *
+ * The decorator uses lenient validation for return values:
+ * - Workflow objects (with 'id' property) are automatically attached
+ * - Non-workflow objects are silently skipped (not attached)
+ * - The original return value is always preserved
+ *
+ * This lenient approach enables:
+ * - Duck-typing: Works with workflow-like objects, not just Workflow instances
+ * - Flexible signatures: Methods can return any type without breaking
+ * - Graceful handling: Edge cases (null, undefined, primitives) don't throw errors
  */
 export function Task(opts: TaskOptions = {}) {
   return function <This, Args extends unknown[], Return>(
@@ -77,7 +110,37 @@ export function Task(opts: TaskOptions = {}) {
         );
 
         if (runnable.length > 0) {
-          await Promise.all(runnable.map((w) => w.run()));
+          const results = await Promise.allSettled(runnable.map((w) => w.run()));
+
+          const rejected = results.filter(
+            (r): r is PromiseRejectedResult => r.status === 'rejected'
+          );
+
+          if (rejected.length > 0) {
+            // Check if error merge strategy is enabled
+            if (opts.errorMergeStrategy?.enabled) {
+              // Extract WorkflowError objects from rejected promises
+              const errors = rejected.map((r) => r.reason as WorkflowError);
+
+              // Merge errors using custom combine() or default merger
+              const mergedError = opts.errorMergeStrategy?.combine
+                ? opts.errorMergeStrategy.combine(errors)
+                : mergeWorkflowErrors(errors, taskName, wf.id, runnable.length);
+
+              // Emit error event with merged error
+              wf.emitEvent({
+                type: 'error',
+                node: wf.node,
+                error: mergedError,
+              });
+
+              // Throw merged error
+              throw mergedError;
+            }
+
+            // Backward compatibility: throw first error
+            throw rejected[0].reason;
+          }
         }
       }
 

package/src/index.ts

@@ -84,6 +84,7 @@ export { WorkflowTreeDebugger } from './debugger/tree-debugger.js';
 export { Observable } from './utils/observable.js';
 export type { Subscription, Observer } from './utils/observable.js';
 export { generateId } from './utils/id.js';
+export { mergeWorkflowErrors } from './utils/workflow-error-utils.js';
 
 // Factory functions
 export {
@@ -136,5 +137,6 @@ export type {
 } from './tools/introspection.js';
 
 // Examples (for reference)
-export { TestCycleWorkflow } from './examples/test-cycle-workflow.js';
-export { TDDOrchestrator } from './examples/tdd-orchestrator.js';
+// Temporarily commented out due to decorator compatibility issues with vitest
+// export { TestCycleWorkflow } from './examples/test-cycle-workflow.js';
+// export { TDDOrchestrator } from './examples/tdd-orchestrator.js';

package/src/types/decorators.ts

@@ -1,3 +1,5 @@
+import type { ErrorMergeStrategy } from './error-strategy.js';
+
 /**
  * Configuration options for @Step decorator
  */
@@ -6,7 +8,7 @@ export interface StepOptions {
   name?: string;
   /** If true, capture state snapshot after step completion */
   snapshotState?: boolean;
-  /** If true, track and emit step duration */
+  /** Track and emit step duration (default: true) */
   trackTiming?: boolean;
   /** If true, log message at step start */
   logStart?: boolean;
@@ -16,10 +18,15 @@ export interface StepOptions {
 
 /**
  * Configuration options for @Task decorator
+ *
+ * @note The decorator uses lenient validation - non-Workflow returns are
+ *       silently skipped. See the @Task decorator JSDoc for details.
  */
 export interface TaskOptions {
   /** Custom task name (defaults to method name) */
   name?: string;
   /** If true, run returned workflows concurrently */
   concurrent?: boolean;
+  /** Strategy for merging errors from concurrent task execution */
+  errorMergeStrategy?: ErrorMergeStrategy;
 }

package/src/types/events.ts

@@ -8,6 +8,7 @@ import type { TokenUsage } from './sdk-primitives.js';
 export type WorkflowEvent =
   // Core workflow events
   | { type: 'childAttached'; parentId: string; child: WorkflowNode }
+  | { type: 'childDetached'; parentId: string; childId: string }
   | { type: 'stateSnapshot'; node: WorkflowNode }
   | { type: 'stepStart'; node: WorkflowNode; step: string }
   | { type: 'stepEnd'; node: WorkflowNode; step: string; duration: number }

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export { generateId } from './id.js';
 export { Observable } from './observable.js';
+export { mergeWorkflowErrors } from './workflow-error-utils.js';
 export type { Subscription, Observer } from './observable.js';

package/src/utils/observable.ts

@@ -12,8 +12,25 @@ export interface Observer<T> {
   complete?: () => void;
 }
 
+/**
+ * Logger interface for Observable error logging
+ * Matches WorkflowLogger.error() signature for compatibility
+ */
+export interface ObservableLogger {
+  error(message: string, data?: unknown): void;
+}
+
 export class Observable<T> {
   private subscribers: Set<Observer<T>> = new Set();
+  private logger?: ObservableLogger;
+
+  /**
+   * Create a new Observable
+   * @param logger Optional logger for error reporting (falls back to console.error)
+   */
+  constructor(logger?: ObservableLogger) {
+    this.logger = logger;
+  }
 
   /**
    * Subscribe to this observable
@@ -28,6 +45,18 @@ export class Observable<T> {
     };
   }
 
+  /**
+   * Log errors using injected logger or fallback to console.error
+   */
+  private logError(message: string, error: unknown): void {
+    if (this.logger) {
+      this.logger.error(message, { error });
+    } else {
+      // Fallback for backward compatibility
+      console.error(message, error);
+    }
+  }
+
   /**
    * Emit a value to all subscribers
    */
@@ -36,7 +65,7 @@ export class Observable<T> {
       try {
         subscriber.next?.(value);
       } catch (err) {
-        console.error('Observable subscriber error:', err);
+        this.logError('Observable subscriber error', err);
       }
     }
   }
@@ -49,7 +78,7 @@ export class Observable<T> {
       try {
         subscriber.error?.(err);
       } catch (e) {
-        console.error('Observable error handler failed:', e);
+        this.logError('Observable error handler failed', e);
       }
     }
   }
@@ -62,7 +91,7 @@ export class Observable<T> {
       try {
         subscriber.complete?.();
       } catch (err) {
-        console.error('Observable complete handler failed:', err);
+        this.logError('Observable complete handler failed', err);
       }
     }
     this.subscribers.clear();