groundswell 0.0.2 → 1.0.0

package/src/__tests__/helpers/index.ts

@@ -1,18 +0,0 @@
-/**
- * Test helper functions for tree validation
- *
- * These helpers validate the 1:1 mirror invariant between the Workflow instance tree
- * and the WorkflowNode tree as specified in PRD Section 12.2.
- *
- * @module helpers/tree-verification
- */
-
-export {
-  collectAllNodes,
-  validateTreeConsistency,
-  verifyBidirectionalLink,
-  verifyOrphaned,
-  verifyNoCycles,
-  verifyTreeMirror,
-  getDepth,
-} from './tree-verification.js';

package/src/__tests__/helpers/tree-verification.ts

@@ -1,257 +0,0 @@
-import type { Workflow } from '../../index.js';
-
-/**
- * Collect all nodes in tree via BFS traversal
- * Throws if circular reference detected
- *
- * @param root - The root workflow node to start traversal from
- * @returns Array of all workflow nodes in the tree
- * @throws Error if circular reference is detected
- *
- * Pattern from: tree-debugger.ts:52-58 (buildNodeMap)
- */
-export function collectAllNodes(root: Workflow): Workflow[] {
-  const nodes: Workflow[] = [];
-  const queue: Workflow[] = [root];
-  const visited = new Set<Workflow>();
-
-  while (queue.length > 0) {
-    const node = queue.shift()!;
-
-    // CRITICAL: Cycle detection
-    if (visited.has(node)) {
-      throw new Error(`Circular reference detected at ${node.node.name}`);
-    }
-
-    visited.add(node);
-    nodes.push(node);
-    queue.push(...node.children);
-  }
-
-  return nodes;
-}
-
-/**
- * Validate tree-wide bidirectional consistency
- * Returns array of inconsistency descriptions (empty if valid)
- *
- * This is the comprehensive validation that checks:
- * 1. Parent → child links in workflow tree
- * 2. Child → parent links in workflow tree
- * 3. Node tree mirrors workflow tree (parent relationship)
- * 4. Node tree mirrors workflow tree (children relationship)
- *
- * @param root - The root workflow to validate
- * @returns Array of error descriptions (empty if tree is consistent)
- */
-export function validateTreeConsistency(root: Workflow): string[] {
-  const errors: string[] = [];
-  const allNodes = collectAllNodes(root);
-
-  allNodes.forEach(node => {
-    // Check parent→child link in workflow tree
-    if (node.parent) {
-      if (!node.parent.children.includes(node)) {
-        errors.push(
-          `[WORKFLOW TREE] Orphaned child: "${node.node.name}" not in parent "${node.parent.node.name}"'s children list`
-        );
-      }
-    } else {
-      // Root node - should not be in anyone's children
-      const parentClaimants = allNodes.filter(n => n.children.includes(node));
-      if (parentClaimants.length > 0) {
-        errors.push(
-          `[WORKFLOW TREE] Root node "${node.node.name}" claimed as child by [${parentClaimants.map(n => n.node.name).join(', ')}]`
-        );
-      }
-    }
-
-    // Check child→parent links
-    node.children.forEach(child => {
-      // Workflow tree check
-      if (child.parent !== node) {
-        errors.push(
-          `[WORKFLOW TREE] Mismatched parent: "${child.node.name}".parent is "${child.parent?.node.name ?? 'null'}", expected "${node.node.name}"`
-        );
-      }
-
-      // CRITICAL: Check node tree mirrors workflow tree - parent relationship
-      if (child.node.parent !== node.node) {
-        errors.push(
-          `[NODE TREE] Mismatched parent: "${child.node.name}".node.parent is "${child.node.parent?.name ?? 'null'}", expected "${node.node.name}"`
-        );
-      }
-
-      // CRITICAL: Check node tree mirrors workflow tree - children relationship
-      if (!node.node.children.includes(child.node)) {
-        errors.push(
-          `[NODE TREE] Orphaned child: "${child.node.name}".node not in parent "${node.node.name}"'s node.children array`
-        );
-      }
-    });
-  });
-
-  return errors;
-}
-
-/**
- * Verify bidirectional link between parent and child in BOTH trees
- * Throws if inconsistency found
- *
- * This is the primary assertion helper for testing attachChild() operations.
- * Verifies:
- * - child.parent === parent (workflow tree)
- * - parent.children includes child (workflow tree)
- * - child.node.parent === parent.node (node tree)
- * - parent.node.children includes child.node (node tree)
- *
- * @param parent - The parent workflow
- * @param child - The child workflow
- * @throws Error if bidirectional link is broken in either tree
- *
- * Usage: parent.attachChild(child); verifyBidirectionalLink(parent, child);
- */
-export function verifyBidirectionalLink(parent: Workflow, child: Workflow): void {
-  // Workflow tree checks
-  if (child.parent !== parent) {
-    throw new Error(
-      `[WORKFLOW TREE] Bidirectional link broken: "${child.node.name}".parent is "${child.parent?.node.name ?? 'null'}", expected "${parent.node.name}"`
-    );
-  }
-
-  if (!parent.children.includes(child)) {
-    throw new Error(
-      `[WORKFLOW TREE] Bidirectional link broken: "${parent.node.name}".children does not contain "${child.node.name}"`
-    );
-  }
-
-  // CRITICAL: Node tree checks (must mirror workflow tree)
-  if (child.node.parent !== parent.node) {
-    throw new Error(
-      `[NODE TREE] Bidirectional link broken: "${child.node.name}".node.parent is "${child.node.parent?.name ?? 'null'}", expected "${parent.node.name}"`
-    );
-  }
-
-  if (!parent.node.children.includes(child.node)) {
-    throw new Error(
-      `[NODE TREE] Bidirectional link broken: "${parent.node.name}".node.children does not contain "${child.node.name}"`
-    );
-  }
-}
-
-/**
- * Verify complete orphaning after detach
- * Confirms that child is no longer attached to any parent in BOTH trees
- *
- * @param child - The child workflow to verify
- * @throws Error if child is not properly orphaned
- *
- * Usage: parent.detachChild(child); verifyOrphaned(child);
- */
-export function verifyOrphaned(child: Workflow): void {
-  if (child.parent !== null) {
-    throw new Error(
-      `Child "${child.node.name}" not orphaned: parent is "${child.parent.node.name}"`
-    );
-  }
-
-  if (child.node.parent !== null) {
-    throw new Error(
-      `Child "${child.node.name}" not orphaned in node tree: parent is "${child.node.parent.name}"`
-    );
-  }
-}
-
-/**
- * Verify no circular references exist in the tree
- * Uses collectAllNodes which throws on circular reference detection
- *
- * @param root - The root workflow to check
- * @throws Error if circular reference is detected
- *
- * Usage: verifyNoCycles(root);
- */
-export function verifyNoCycles(root: Workflow): void {
-  const visited = new Set<Workflow>();
-  const allNodes = collectAllNodes(root);
-
-  allNodes.forEach(node => {
-    if (visited.has(node)) {
-      throw new Error(`Circular reference detected: node "${node.node.name}" visited twice`);
-    }
-    visited.add(node);
-  });
-}
-
-/**
- * Verify tree mirror invariant (1:1 correspondence)
- * This is the CRITICAL invariant from PRD Section 12.2
- *
- * For every relationship in the workflow tree, there MUST be an equivalent relationship in the node tree:
- * - If node.parent exists, it must equal wfNode.parent.node
- * - If node.parent is null, wfNode.parent must be null
- * - node.children.length must equal wfNode.children.length
- * - node.children[index] must equal wfNode.children[index].node
- *
- * @param workflowRoot - The root workflow to verify
- * @throws Error if mirror invariant is violated
- *
- * Usage: verifyTreeMirror(root);
- */
-export function verifyTreeMirror(workflowRoot: Workflow): void {
-  const allNodes = collectAllNodes(workflowRoot);
-
-  allNodes.forEach(wfNode => {
-    const node = wfNode.node;
-
-    // Verify parent relationship mirrors
-    if (wfNode.parent) {
-      if (node.parent !== wfNode.parent.node) {
-        throw new Error(
-          `[MIRROR] Parent mismatch: "${wfNode.node.name}".parent is "${node.parent?.name}", expected "${wfNode.parent.node.name}"`
-        );
-      }
-    } else {
-      if (node.parent !== null) {
-        throw new Error(
-          `[MIRROR] Parent mismatch: "${wfNode.node.name}".parent is "${node.parent.name}", expected null`
-        );
-      }
-    }
-
-    // Verify children relationship mirrors
-    if (node.children.length !== wfNode.children.length) {
-      throw new Error(
-        `[MIRROR] Children count mismatch: "${wfNode.node.name}" has ${wfNode.children.length} workflow children but ${node.children.length} node children`
-      );
-    }
-
-    wfNode.children.forEach((childWf, index) => {
-      if (node.children[index] !== childWf.node) {
-        throw new Error(
-          `[MIRROR] Child mismatch at index ${index}: expected "${childWf.node.name}", got "${node.children[index].name}"`
-        );
-      }
-    });
-  });
-}
-
-/**
- * Get depth of node in tree
- * Depth is the number of edges from the node to the root
- * Root has depth 0, its children have depth 1, etc.
- *
- * @param node - The workflow node to calculate depth for
- * @returns The depth of the node (0 for root)
- */
-export function getDepth(node: Workflow): number {
-  let depth = 0;
-  let current: Workflow | null = node;
-
-  while (current !== null) {
-    depth++;
-    current = current.parent;
-  }
-
-  return depth - 1; // Subtract 1 for the node itself
-}

package/src/__tests__/integration/agent-workflow.test.ts

@@ -1,256 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { z } from 'zod';
-import {
-  Workflow,
-  Prompt,
-  Step,
-  WorkflowObserver,
-  WorkflowEvent,
-  runInContext,
-  type AgentExecutionContext,
-  createEventTreeHandle,
-} from '../../index.js';
-
-// Mock workflow that simulates agent prompt execution within steps
-class MockAgentWorkflow extends Workflow {
-  public events: WorkflowEvent[] = [];
-
-  @Step({ name: 'step1' })
-  async executeStep1(): Promise<string> {
-    return 'step1-result';
-  }
-
-  @Step({ name: 'step2' })
-  async executeStep2(): Promise<string> {
-    return 'step2-result';
-  }
-
-  async run(): Promise<string> {
-    this.setStatus('running');
-    await this.executeStep1();
-    await this.executeStep2();
-    this.setStatus('completed');
-    return 'done';
-  }
-}
-
-describe('Agent-Workflow Integration', () => {
-  it('should establish context in @Step decorated methods', async () => {
-    const workflow = new MockAgentWorkflow('TestWorkflow');
-    const events: WorkflowEvent[] = [];
-
-    const observer: WorkflowObserver = {
-      onLog: () => {},
-      onEvent: (event) => events.push(event),
-      onStateUpdated: () => {},
-      onTreeChanged: () => {},
-    };
-
-    workflow.addObserver(observer);
-    await workflow.run();
-
-    // Should have step start/end events
-    const stepStarts = events.filter((e) => e.type === 'stepStart');
-    const stepEnds = events.filter((e) => e.type === 'stepEnd');
-
-    expect(stepStarts).toHaveLength(2);
-    expect(stepEnds).toHaveLength(2);
-  });
-
-  it('should track events emitted from within step context', async () => {
-    const emittedEvents: WorkflowEvent[] = [];
-
-    class ContextTrackingWorkflow extends Workflow {
-      @Step({ name: 'tracked-step' })
-      async trackedStep(): Promise<void> {
-        // This simulates what happens when Agent.prompt() is called
-        // The context should be available
-      }
-
-      async run(): Promise<void> {
-        this.setStatus('running');
-        await this.trackedStep();
-        this.setStatus('completed');
-      }
-    }
-
-    const workflow = new ContextTrackingWorkflow('ContextTest');
-    const observer: WorkflowObserver = {
-      onLog: () => {},
-      onEvent: (event) => emittedEvents.push(event),
-      onStateUpdated: () => {},
-      onTreeChanged: () => {},
-    };
-
-    workflow.addObserver(observer);
-    await workflow.run();
-
-    // Verify step events were emitted
-    expect(emittedEvents.some((e) => e.type === 'stepStart')).toBe(true);
-    expect(emittedEvents.some((e) => e.type === 'stepEnd')).toBe(true);
-  });
-
-  it('should support functional workflow pattern with step()', async () => {
-    const events: WorkflowEvent[] = [];
-
-    const workflow = new Workflow<string>({ name: 'FunctionalWorkflow' }, async (ctx) => {
-      await ctx.step('step-a', async () => {
-        return 'a';
-      });
-
-      await ctx.step('step-b', async () => {
-        return 'b';
-      });
-
-      return 'completed';
-    });
-
-    const observer: WorkflowObserver = {
-      onLog: () => {},
-      onEvent: (event) => events.push(event),
-      onStateUpdated: () => {},
-      onTreeChanged: () => {},
-    };
-
-    workflow.addObserver(observer);
-    const result = await workflow.run();
-
-    expect(result).toEqual({
-      data: 'completed',
-      node: expect.any(Object),
-      duration: expect.any(Number),
-    });
-
-    const stepStarts = events.filter((e) => e.type === 'stepStart');
-    const stepEnds = events.filter((e) => e.type === 'stepEnd');
-
-    expect(stepStarts).toHaveLength(2);
-    expect(stepEnds).toHaveLength(2);
-  });
-
-  it('should nest step events under workflow in tree', async () => {
-    const workflow = new Workflow<string>({ name: 'TreeTestWorkflow' }, async (ctx) => {
-      await ctx.step('nested-step', async () => {
-        return 'nested';
-      });
-
-      return 'done';
-    });
-
-    const result = await workflow.run();
-    const node = workflow.getNode();
-
-    // Check that the workflow node has children (the step nodes)
-    expect(node.children.length).toBeGreaterThan(0);
-  });
-
-  it('should propagate context through async boundaries', async () => {
-    let contextWasAvailable = false;
-
-    const workflow = new Workflow<boolean>({ name: 'AsyncContextWorkflow' }, async (ctx) => {
-      await ctx.step('async-step', async () => {
-        // Simulate async operation
-        await new Promise((resolve) => setTimeout(resolve, 10));
-
-        // The context should still be available after async boundary
-        // This is verified by the step completing successfully
-        contextWasAvailable = true;
-        return 'async-result';
-      });
-
-      return contextWasAvailable;
-    });
-
-    const result = await workflow.run();
-    // For functional workflows, result is WorkflowResult<T>
-    expect((result as { data: boolean }).data).toBe(true);
-  });
-
-  it('should create EventTreeHandle from workflow', async () => {
-    const workflow = new Workflow<void>({ name: 'EventTreeWorkflow' }, async (ctx) => {
-      await ctx.step('tree-step', async () => {});
-    });
-
-    await workflow.run();
-
-    const treeHandle = createEventTreeHandle(workflow.getNode());
-    expect(treeHandle.root).toBeDefined();
-    expect(treeHandle.root.name).toBe('EventTreeWorkflow');
-  });
-
-  it('should handle errors in steps', async () => {
-    const events: WorkflowEvent[] = [];
-
-    const workflow = new Workflow<void>({ name: 'ErrorWorkflow' }, async (ctx) => {
-      await ctx.step('failing-step', async () => {
-        throw new Error('Step failed');
-      });
-    });
-
-    const observer: WorkflowObserver = {
-      onLog: () => {},
-      onEvent: (event) => events.push(event),
-      onStateUpdated: () => {},
-      onTreeChanged: () => {},
-    };
-
-    workflow.addObserver(observer);
-
-    await expect(workflow.run()).rejects.toThrow('Step failed');
-
-    const errorEvents = events.filter((e) => e.type === 'error');
-    // Error is emitted both from the step context and from the workflow
-    expect(errorEvents.length).toBeGreaterThanOrEqual(1);
-    expect(workflow.status).toBe('failed');
-  });
-});
-
-describe('Prompt Integration', () => {
-  it('should create type-safe prompts with Zod schemas', () => {
-    const responseSchema = z.object({
-      answer: z.string(),
-      confidence: z.number().min(0).max(1),
-    });
-
-    const prompt = new Prompt({
-      user: 'What is 2 + 2?',
-      responseFormat: responseSchema,
-    });
-
-    // Valid response
-    const valid = prompt.validateResponse({ answer: '4', confidence: 0.99 });
-    expect(valid).toEqual({ answer: '4', confidence: 0.99 });
-
-    // Invalid response should throw
-    expect(() => prompt.validateResponse({ answer: '4' })).toThrow();
-  });
-
-  it('should support complex nested schemas', () => {
-    const schema = z.object({
-      items: z.array(
-        z.object({
-          id: z.number(),
-          name: z.string(),
-          tags: z.array(z.string()),
-        })
-      ),
-      metadata: z.object({
-        total: z.number(),
-        page: z.number(),
-      }),
-    });
-
-    const prompt = new Prompt({
-      user: 'List items',
-      responseFormat: schema,
-    });
-
-    const result = prompt.validateResponse({
-      items: [{ id: 1, name: 'Item 1', tags: ['a', 'b'] }],
-      metadata: { total: 1, page: 1 },
-    });
-
-    expect(result.items).toHaveLength(1);
-    expect(result.metadata.total).toBe(1);
-  });
-});