groundswell 0.0.2 → 1.0.0

package/scripts/generate-llms-full.ts

@@ -1,206 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Generates llms_full.txt by combining:
- * 1. README.md and its linked markdown documentation files
- * 2. Examples README and all example source files
- *
- * Future-proof design:
- * - Auto-discovers markdown files linked from README.md (docs/*.md pattern)
- * - Auto-discovers all example files matching examples/examples/*.ts
- * - New docs and examples are automatically included without script changes
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const ROOT_DIR = path.resolve(__dirname, "..");
-const OUTPUT_FILE = path.join(ROOT_DIR, "llms_full.txt");
-
-interface Section {
-  title: string;
-  content: string;
-  filePath?: string;
-}
-
-function readFile(filePath: string): string {
-  try {
-    return fs.readFileSync(filePath, "utf-8");
-  } catch (error) {
-    console.warn(`Warning: Could not read ${filePath}`);
-    return "";
-  }
-}
-
-function extractMarkdownLinks(content: string, baseDir: string): string[] {
-  // Match markdown links: [text](path.md) - only .md files
-  const linkRegex = /\[([^\]]+)\]\(([^)]+\.md)\)/g;
-  const links: string[] = [];
-  let match;
-
-  while ((match = linkRegex.exec(content)) !== null) {
-    const linkPath = match[2];
-    // Only include relative links (not http/https)
-    if (!linkPath.startsWith("http://") && !linkPath.startsWith("https://")) {
-      const absolutePath = path.resolve(baseDir, linkPath);
-      if (fs.existsSync(absolutePath) && !links.includes(absolutePath)) {
-        links.push(absolutePath);
-      }
-    }
-  }
-
-  return links;
-}
-
-function discoverDocsMarkdown(): string[] {
-  const docsDir = path.join(ROOT_DIR, "docs");
-  if (!fs.existsSync(docsDir)) {
-    return [];
-  }
-
-  return fs
-    .readdirSync(docsDir)
-    .filter((file) => file.endsWith(".md"))
-    .map((file) => path.join(docsDir, file))
-    .sort();
-}
-
-function discoverExamples(): string[] {
-  const examplesDir = path.join(ROOT_DIR, "examples", "examples");
-  if (!fs.existsSync(examplesDir)) {
-    return [];
-  }
-
-  return fs
-    .readdirSync(examplesDir)
-    .filter((file) => file.endsWith(".ts"))
-    .sort() // Sorting ensures NN- prefixed files are in order
-    .map((file) => path.join(examplesDir, file));
-}
-
-function formatSection(section: Section): string {
-  const separator = "=".repeat(80);
-  const relativePath = section.filePath
-    ? path.relative(ROOT_DIR, section.filePath)
-    : "";
-
-  let header = `${separator}\n${section.title}`;
-  if (relativePath) {
-    header += `\nFile: ${relativePath}`;
-  }
-  header += `\n${separator}\n\n`;
-
-  return header + section.content.trim() + "\n\n";
-}
-
-function generateLlmsFull(): void {
-  const sections: Section[] = [];
-  const processedFiles = new Set<string>();
-
-  // 1. Main README
-  const readmePath = path.join(ROOT_DIR, "README.md");
-  const readmeContent = readFile(readmePath);
-  if (readmeContent) {
-    sections.push({
-      title: "PROJECT README",
-      content: readmeContent,
-      filePath: readmePath,
-    });
-    processedFiles.add(readmePath);
-  }
-
-  // 2. Documentation files from docs/ directory
-  // First, get links from README to preserve intended order
-  const linkedDocs = extractMarkdownLinks(readmeContent, ROOT_DIR);
-  // Then discover all docs to catch any not linked
-  const allDocs = discoverDocsMarkdown();
-
-  // Process linked docs first (preserves README order)
-  for (const docPath of linkedDocs) {
-    if (
-      docPath.includes("/docs/") &&
-      !processedFiles.has(docPath) &&
-      fs.existsSync(docPath)
-    ) {
-      const content = readFile(docPath);
-      const fileName = path.basename(docPath, ".md").toUpperCase();
-      sections.push({
-        title: `DOCUMENTATION: ${fileName}`,
-        content,
-        filePath: docPath,
-      });
-      processedFiles.add(docPath);
-    }
-  }
-
-  // Add any docs not linked from README
-  for (const docPath of allDocs) {
-    if (!processedFiles.has(docPath)) {
-      const content = readFile(docPath);
-      const fileName = path.basename(docPath, ".md").toUpperCase();
-      sections.push({
-        title: `DOCUMENTATION: ${fileName}`,
-        content,
-        filePath: docPath,
-      });
-      processedFiles.add(docPath);
-    }
-  }
-
-  // 3. Examples README
-  const examplesReadmePath = path.join(ROOT_DIR, "examples", "README.md");
-  if (fs.existsSync(examplesReadmePath)) {
-    const content = readFile(examplesReadmePath);
-    sections.push({
-      title: "EXAMPLES OVERVIEW",
-      content,
-      filePath: examplesReadmePath,
-    });
-    processedFiles.add(examplesReadmePath);
-  }
-
-  // 4. All example source files
-  const examples = discoverExamples();
-  for (const examplePath of examples) {
-    const content = readFile(examplePath);
-    const fileName = path.basename(examplePath);
-    // Extract example number and name from filename (e.g., "01-basic-workflow.ts")
-    const match = fileName.match(/^(\d+)-(.+)\.ts$/);
-    const exampleName = match
-      ? `Example ${parseInt(match[1])}: ${match[2].replace(/-/g, " ")}`
-      : fileName;
-
-    sections.push({
-      title: `EXAMPLE: ${exampleName.toUpperCase()}`,
-      content,
-      filePath: examplePath,
-    });
-  }
-
-  // Build output
-  const header = `GROUNDSWELL - LLM DOCUMENTATION
-Generated: ${new Date().toISOString()}
-${"=".repeat(80)}
-
-This file contains the complete documentation and examples for the Groundswell project.
-It is auto-generated by scripts/generate-llms-full.ts
-
-Contents:
-${sections.map((s, i) => `  ${i + 1}. ${s.title}`).join("\n")}
-
-`;
-
-  const output =
-    header + sections.map((section) => formatSection(section)).join("\n");
-
-  // Write output
-  fs.writeFileSync(OUTPUT_FILE, output);
-  console.log(`Generated ${path.relative(process.cwd(), OUTPUT_FILE)}`);
-  console.log(`Total sections: ${sections.length}`);
-  console.log(`Total size: ${(output.length / 1024).toFixed(1)} KB`);
-}
-
-// Run
-generateLlmsFull();

package/src/__tests__/adversarial/attachChild-performance.test.ts

@@ -1,216 +0,0 @@
-/**
- * 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(): Promise<string> {
-    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: any = 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: any = 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: any = 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
-  });
-});

package/src/__tests__/adversarial/circular-reference.test.ts

@@ -1,101 +0,0 @@
-/**
- * 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(): Promise<string> {
-    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);
-  });
-});

package/src/__tests__/adversarial/complex-circular-reference.test.ts

@@ -1,139 +0,0 @@
-/**
- * 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
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { Workflow } from '../../index.js';
-
-/**
- * SimpleWorkflow class for testing
- * Pattern from: src/__tests__/adversarial/circular-reference.test.ts:20-26
- */
-class SimpleWorkflow extends Workflow {
-  async run(): Promise<string> {
-    this.setStatus('running');
-    this.setStatus('completed');
-    return 'done';
-  }
-}
-
-describe('Adversarial: Complex Circular Reference Detection', () => {
-  /**
-   * Setup: Mock console methods to capture error messages
-   * Pattern from: src/__tests__/adversarial/circular-reference.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: Immediate Circular Reference (depth 1)
-   *
-   * Validates that attachChild() prevents creating a cycle when a child
-   * attempts to attach its immediate parent as its child.
-   *
-   * Hierarchy: root -> child1
-   * Cycle attempt: child1.attachChild(root)
-   *
-   * Expected: Error thrown with message containing 'circular' OR 'cycle' OR 'ancestor'
-   */
-  it('should throw when attaching immediate parent as child (depth 1)', () => {
-    // ARRANGE: Create 2-level hierarchy (root, child1)
-    const root = new SimpleWorkflow('Root');
-    const child1 = new SimpleWorkflow('Child1', root);
-
-    // Verify initial state
-    // CRITICAL: Constructor auto-attaches child to parent at workflow.ts:113-116
-    expect(child1.parent).toBe(root);
-    expect(root.children).toContain(child1);
-
-    // ACT & ASSERT: Attempting to attach parent as child should throw
-    // This validates isDescendantOf() detects the immediate ancestor
-    expect(() => child1.attachChild(root)).toThrow(/circular|cycle|ancestor/i);
-  });
-
-  /**
-   * Test 2: Two-Level Circular Reference (depth 2)
-   *
-   * Validates that attachChild() prevents creating a cycle when a grandchild
-   * attempts to attach its grandparent (root) as its child.
-   *
-   * Hierarchy: root -> child1 -> child2
-   * Cycle attempt: child2.attachChild(root)
-   *
-   * Expected: Error thrown with message containing 'circular' OR 'cycle' OR 'ancestor'
-   */
-  it('should throw when attaching grandparent as child (depth 2)', () => {
-    // ARRANGE: Create 3-level hierarchy (root, child1, child2)
-    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 validates isDescendantOf() traverses the full ancestor chain
-    expect(() => child2.attachChild(root)).toThrow(/circular|cycle|ancestor/i);
-  });
-
-  /**
-   * Test 3: Three-Level Circular Reference (depth 3)
-   *
-   * Validates that attachChild() prevents creating a cycle when a great-grandchild
-   * attempts to attach its great-grandparent (root) as its child.
-   *
-   * Hierarchy: root -> child1 -> child2 -> child3
-   * Cycle attempt: child3.attachChild(root)
-   *
-   * Expected: Error thrown with message containing 'circular' OR 'cycle' OR 'ancestor'
-   *
-   * This test provides NEW coverage not present in circular-reference.test.ts
-   * which only tests depth 1 (immediate parent) and depth 2 (ancestor).
-   */
-  it('should throw when attaching great-grandparent as child (depth 3)', () => {
-    // ARRANGE: Create 4-level hierarchy (root, child1, child2, child3)
-    const root = new SimpleWorkflow('Root');
-    const child1 = new SimpleWorkflow('Child1', root);   // root -> child1
-    const child2 = new SimpleWorkflow('Child2', child1); // root -> child1 -> child2
-    const child3 = new SimpleWorkflow('Child3', child2); // root -> child1 -> child2 -> child3
-
-    // Verify initial state
-    // CRITICAL: Constructor auto-attaches at workflow.ts:113-116
-    expect(child3.parent).toBe(child2);
-    expect(child2.parent).toBe(child1);
-    expect(child1.parent).toBe(root);
-    expect(root.children).toContain(child1);
-    expect(child1.children).toContain(child2);
-    expect(child2.children).toContain(child3);
-
-    // ACT & ASSERT: Attempting to attach root as child of child3 should throw
-    // This validates isDescendantOf() detects deep ancestors (3+ levels)
-    expect(() => child3.attachChild(root)).toThrow(/circular|cycle|ancestor/i);
-  });
-});