groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T4S2/PRP.md

@@ -1,792 +0,0 @@
-# Product Requirement Prompt (PRP): Implement Public `isDescendantOf` API
-
-**Work Item**: P1.M3.T4.S2 - Implement public `isDescendantOf` if approved
-**PRD Reference**: Issue 9 - Steps Not in Tree Structure (Bug Report Note)
-**Implementation Target**: `src/core/workflow.ts:162`
-**S1 Decision**: **APPROVED** - Make public with confidence 9/10
-
----
-
-## Goal
-
-**Feature Goal**: Change the `isDescendantOf()` method visibility from `private` to `public`, add comprehensive JSDoc documentation with security warning, and ensure the method has appropriate parameter validation.
-
-**Deliverable**:
-1. `isDescendantOf()` method changed from `private` to `public` in `src/core/workflow.ts:162`
-2. Comprehensive JSDoc documentation with `@warning` tag for security implications
-3. Optional: Parameter validation for the `ancestor` parameter
-4. Update to security documentation guide
-5. Tests pass (no changes to test logic needed)
-
-**Success Definition**:
-- Method is publicly accessible without casting to `any`
-- JSDoc includes `@warning` about topology information disclosure
-- All existing tests pass without modification
-- New tests (if added) verify public accessibility and parameter validation
-
-## User Persona
-
-**Target User**: Developer using the Groundswell workflow engine who needs to check workflow hierarchy relationships programmatically.
-
-**Use Case**: A developer building a workflow-based application needs to validate that a workflow belongs to a specific tree branch before executing an operation.
-
-**User Journey**:
-1. User has references to two workflow instances
-2. User calls `childWorkflow.isDescendantOf(rootWorkflow)`
-3. Method returns `true` if child is in root's hierarchy, `false` otherwise
-4. User proceeds with conditional logic based on result
-
-**Pain Points Addressed**:
-- Users currently must manually traverse `parent` chain (error-prone, forget cycle detection)
-- Current workaround requires casting to `any` to access private method
-- Inconsistent with other public hierarchy properties (`parent`, `children`)
-
-## Why
-
-- **API Ergonomics**: `isDescendantOf()` provides cleaner interface than manual tree traversal
-- **User Needs**: Introspection tools and examples show users want hierarchy navigation
-- **No Security Risk**: Does NOT expose new information beyond existing `parent`/`children` properties
-- **Low Implementation Cost**: Change one keyword, add documentation; already battle-tested (25+ tests)
-- **Competitive Differentiator**: No major workflow engine exposes this API publicly
-- **S1 Approval**: Comprehensive research and recommendation supports this change
-
-## What
-
-### Success Criteria
-
-- [ ] `isDescendantOf()` method changed from `private` to `public` at `src/core/workflow.ts:162`
-- [ ] Comprehensive JSDoc documentation added with security `@warning`
-- [ ] All existing tests pass (25+ tests already cover this method indirectly)
-- [ ] No breaking changes to existing functionality
-- [ ] Security documentation updated with `isDescendantOf()` section
-
----
-
-## All Needed Context
-
-### Context Completeness Check
-
-_This PRP passes the "No Prior Knowledge" test - someone unfamiliar with the codebase would have everything needed to implement this successfully._
-
-### Documentation & References
-
-```yaml
-# MUST READ - S1 Research Decision (APPROVED)
-- file: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T4S1/RECOMMENDATION.md
-  why: Final recommendation to make isDescendantOf public with confidence 9/10
-  section: Lines 1-50 (Executive Summary and Decision Matrix)
-  critical: Decision is APPROVED with safeguards (JSDoc warning, security docs)
-  gotcha: This is a BREAKING API change per Semantic Versioning (requires major version bump)
-
-# MUST READ - Current Implementation
-- file: src/core/workflow.ts
-  why: The isDescendantOf() implementation at lines 162-180, currently private
-  pattern: Private method using iterative traversal with visited Set for cycle detection
-  gotcha: No parameter validation currently - relies on TypeScript type system
-
-# MUST READ - JSDoc Documentation Patterns
-- file: src/core/workflow.ts
-  why: Examples of comprehensive JSDoc patterns for public methods
-  pattern: attachChild (lines 224-276), detachChild (lines 318-369)
-  gotcha: Codebase uses @throws, @example, detailed descriptions with sections
-  critical: No existing @warning tags - this will be first security-warning JSDoc
-
-# MUST READ - Security Implications Analysis
-- file: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T4S1/research/security_implications_analysis.md
-  why: Security assessment showing NO new information exposed
-  section: Lines 58-68 (Comparison with Existing Public APIs)
-  critical: parent and children already public - isDescendantOf is convenience only
-  gotcha: Applications must implement their own access control if exposing workflows via API
-
-# MUST READ - Security Guide (to update)
-- file: plan/001_d3bb02af4886/docs/research/general/introspection-security-guide.md
-  why: Security patterns for introspection and hierarchy exposure
-  section: Lines 1-100 (Threat Model and Introspection Attack Vectors)
-  critical: Add isDescendantOf() section documenting hierarchy information disclosure
-  gotcha: Groundswell has NO built-in authentication/authorization - security is app's responsibility
-
-# MUST READ - Parameter Validation Patterns
-- file: src/core/workflow.ts
-  why: Patterns for validating parameters in public methods
-  pattern: attachChild (lines 277-299) - Array.includes(), reference equality checks
-  gotcha: Most validation is implicit via TypeScript types; explicit checks for edge cases
-  critical: No instanceof checks - codebase trusts TypeScript types
-
-# MUST READ - Testing Patterns
-- file: src/__tests__/adversarial/circular-reference.test.ts
-  why: Tests for isDescendantOf behavior (currently cast to 'any' for access)
-  pattern: Uses (workflow as any).isDescendantOf() to test private method
-  gotcha: After making public, tests can call method directly without casting
-  critical: 25+ test cases already cover this method via attachChild circular reference detection
-
-# MUST READ - Industry Comparison
-- file: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T4S1/workflow_engine_ancestry_api_research.md
-  why: Groundswell would be UNIQUE in exposing public isDescendantOf API
-  section: Lines 450-470 (API Exposure Matrix)
-  critical: NO major workflow engine (Airflow, Temporal, Prefect) exposes this publicly
-  gotcha: Not an anti-pattern, just different from industry
-
-# MUST READ - External JSDoc Best Practices
-- url: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
-  why: TypeScript's official JSDoc reference
-  section: @throws, @example, @warning tags
-
-# MUST READ - Semantic Versioning Implications
-- url: https://semver.org/
-  why: Making private method public is a MAJOR breaking change
-  critical: Requires version bump from X.Y.Z to (X+1).0.0
-  gotcha: Even though implementation doesn't change, API surface area increases
-
-# REFERENCE - Current Usage Site
-- file: src/core/workflow.ts
-  why: Single call site at line 293 in attachChild() method
-  pattern: if (this.isDescendantOf(child)) - circular reference detection
-  gotcha: This internal usage continues unchanged after visibility change
-```
-
-### Current Codebase Tree (relevant to isDescendantOf)
-
-```bash
-src/
-├── core/
-│   └── workflow.ts              # isDescendantOf at line 162 (private → public)
-│                                # attachChild usage at line 293
-│                                # public parent/children properties at 49-52
-├── types/
-│   └── workflow.ts              # WorkflowNode interface with parent/children
-├── tools/
-│   └── introspection.ts         # Public introspection tools (read_ancestor_chain, etc.)
-└── __tests__/
-    ├── adversarial/
-    │   ├── circular-reference.test.ts     # Tests for isDescendantOf behavior
-    │   ├── complex-circular-reference.test.ts
-    │   ├── deep-hierarchy-stress.test.ts
-    │   └── attachChild-performance.test.ts
-    └── unit/
-        └── workflow-detachChild.test.ts   # Example of public method test patterns
-```
-
-### Desired Codebase Tree with files to be added and responsibility of file
-
-```bash
-# NO new files needed - only modifications to existing files
-
-# CHANGES:
-src/core/workflow.ts              # CHANGE: private → public, add JSDoc
-plan/.../introspection-security-guide.md  # CHANGE: Add isDescendantOf section
-```
-
-### Known Gotchas of Our Codebase
-
-```typescript
-// CRITICAL: isDescendantOf is private - changing to public is a BREAKING API change
-// Per Semantic Versioning, this requires a MAJOR version bump (X.0.0 → (X+1).0.0)
-
-// CRITICAL: Groundswell has NO built-in authentication or authorization
-// Security is entirely the application's responsibility
-
-// CRITICAL: parent and children properties are already PUBLIC
-// isDescendantOf does NOT expose any new information
-
-// CRITICAL: No instanceof checks for parameter validation in codebase
-// Codebase relies on TypeScript type system for type safety
-
-// CRITICAL: isDescendantOf uses iterative while loop (not recursive)
-// This is intentional for stack safety at extreme depths (1000+ levels)
-
-// CRITICAL: Cycle detection uses visited Set pattern
-// Same pattern as getRoot() and getRootObservers()
-
-// CRITICAL: @warning JSDoc tag does NOT exist in codebase yet
-// This will be the first usage of @warning for security documentation
-
-// CRITICAL: Tests currently use (workflow as any).isDescendantOf()
-// After making public, can call directly - but existing tests still work
-
-// CRITICAL: Method returns boolean, NOT throws for non-descendant
-// Only throws Error if circular reference detected during traversal
-
-// CRITICAL: JSDoc pattern uses markdown with bold headers
-// See attachChild() for example: **Structural Changes:**, **Invariants Maintained:**
-```
-
----
-
-## Implementation Blueprint
-
-### Data Models and Structure
-
-No new data models needed. The `Workflow` class already exists with all necessary structure.
-
-### Implementation Tasks (ordered by dependencies)
-
-```yaml
-Task 1: MODIFY src/core/workflow.ts - Change Visibility
-  - CHANGE: Line 162 from `private isDescendantOf` to `public isDescendantOf`
-  - LOCATION: src/core/workflow.ts:162
-  - PRESERVE: All existing implementation logic (lines 163-180)
-  - NAMING: Keep method name exactly as is (no rename)
-
-Task 2: ADD JSDoc Documentation
-  - ADD: Comprehensive JSDoc comment BEFORE line 162
-  - FOLLOW: Pattern from attachChild() method (lines 224-276)
-  - INCLUDE:
-    - One-line summary
-    - Detailed description paragraph
-    - @warning tag about topology information disclosure
-    - @param tag for ancestor parameter
-    - @returns tag describing boolean return
-    - @throws {Error} tag for cycle detection
-    - @example tags showing usage patterns
-  - PLACEMENT: Lines 152-161 (replace existing private JSDoc)
-
-Task 3: CONSIDER Adding Parameter Validation (OPTIONAL)
-  - DECISION POINT: Add instanceof check or rely on TypeScript types?
-  - IF ADDING: Insert at line 163 (first line of method body)
-  - PATTERN: Follow attachChild() validation style
-  - EXAMPLE:
-    ```typescript
-    if (!(ancestor instanceof Workflow)) {
-      throw new TypeError(`Expected Workflow instance, got ${typeof ancestor}`);
-    }
-    ```
-  - NOTE: Codebase typically relies on TypeScript types - this is optional
-
-Task 4: MODIFY Security Documentation
-  - ADD: New section to plan/.../introspection-security-guide.md
-  - LOCATION: After "Threat Model" section, before "Implementation Checklist"
-  - TITLE: "### Threat 5: Topology Exposure via isDescendantOf()"
-  - INCLUDE: What information is exposed, why risk is LOW, mitigation recommendations
-  - PATTERN: Follow existing threat section structure (Threat 1-4)
-
-Task 5: VERIFY Tests Pass
-  - RUN: Full test suite to ensure no regressions
-  - VERIFY: All 25+ existing tests still pass
-  - CHECK: circular-reference.test.ts, complex-circular-reference.test.ts, deep-hierarchy-stress.test.ts
-  - EXPECTED: All tests pass without modification (private → public is backward compatible)
-
-Task 6: CONSIDER Adding Public API Tests (OPTIONAL)
-  - CREATE: src/__tests__/unit/workflow-isDescendantOf.test.ts (if desired)
-  - IMPLEMENT: Tests that call isDescendantOf() directly without (as any) cast
-  - FOLLOW: Pattern from workflow-detachChild.test.ts
-  - COVERAGE: Happy path, edge cases (self, null, unrelated workflows)
-  - NOTE: Existing tests already cover behavior - new tests would verify public accessibility only
-```
-
-### Implementation Patterns & Key Details
-
-```typescript
-// CRITICAL: JSDoc Pattern for Security-Sensitive Public API
-/**
- * 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 {
-  // Implementation unchanged (lines 163-180)
-}
-
-// CRITICAL: Security Documentation Pattern
-// Add to introspection-security-guide.md after Threat 4:
-
-/**
-### Threat 5: Topology Exposure via isDescendantOf
-
-**Attack Scenario:**
-```
-Attacker → Calls workflow.isDescendantOf(suspectWorkflow)
-         → Learns hierarchy relationship between workflows
-         → Maps workflow tree structure
-         → Extracts business intelligence from topology
-```
-
-**Risk Level:** LOW (same as current exposure)
-
-**Rationale:**
-- `parent` and `children` properties are already public
-- `getNode()` exposes full tree structure
-- `isDescendantOf()` only provides convenience, not new information
-- Attacker can already traverse tree manually
-
-**Affected Method:** `Workflow.isDescendantOf()` (newly public)
-
-**Mitigation:**
-1. **Application-Level Access Control** - If exposing workflows via API:
-   ```typescript
-   // Validate user has permission to access workflow
-   if (!user.canAccessWorkflow(workflowId)) {
-     throw new Error('Unauthorized');
-   }
-   // Only then allow isDescendantOf calls
-   ```
-
-2. **Filter Hierarchy Information** - For unauthenticated users:
-   ```typescript
-   // Return filtered view without hierarchy
-   const filteredWorkflow = {
-     id: workflow.id,
-     name: workflow.name,
-     // Omit parent, children, isDescendantOf
-   };
-   ```
-
-3. **Audit Topology Access** - Log calls to isDescendantOf:
-   ```typescript
-   auditLog.log({
-     timestamp: Date.now(),
-     userId: user.id,
-     action: 'isDescendantOf',
-     workflowId: workflow.id,
-     ancestorId: ancestor.id
-   });
-   ```
-
-**Recommendation:** Document that applications should implement access control
-if exposing workflows via APIs. The library itself provides no built-in security.
-*/
-```
-
-### Integration Points
-
-```yaml
-CODE CHANGES:
-  - file: src/core/workflow.ts
-    line: 152-161 (JSDoc section)
-    change: Replace existing private JSDoc with comprehensive public JSDoc
-  - file: src/core/workflow.ts
-    line: 162
-    change: `private isDescendantOf` → `public isDescendantOf`
-
-DOCUMENTATION CHANGES:
-  - file: plan/001_d3bb02af4886/docs/research/general/introspection-security-guide.md
-    add: New Threat 5 section for isDescendantOf topology exposure
-    location: After Threat 4 (Denial of Service), before Implementation Checklist
-
-NO BREAKING CHANGES:
-  - All existing code using isDescendantOf internally continues unchanged
-  - attachChild() usage at line 293 unaffected
-  - All existing tests pass without modification
-```
-
----
-
-## Validation Loop
-
-### Level 1: Syntax & Style (Immediate Feedback)
-
-```bash
-# Run after making changes to workflow.ts
-# From project root
-
-# Check TypeScript compilation
-npm run build
-# Expected: No compilation errors
-
-# Type checking
-npx tsc --noEmit
-# Expected: No type errors
-
-# If using ESLint/prettier (check package.json for scripts)
-npm run lint
-# Expected: No linting errors
-
-# Expected: Zero errors. If errors exist, READ output and fix before proceeding.
-```
-
-### Level 2: Unit Tests (Component Validation)
-
-```bash
-# Test specific functionality
-npm test -- circular-reference
-npm test -- complex-circular-reference
-npm test -- deep-hierarchy-stress
-npm test -- attachChild-performance
-
-# Full test suite
-npm test
-
-# Expected: All tests pass. isDescendantOf is already tested indirectly via attachChild tests.
-# No test modifications should be needed.
-```
-
-### Level 3: Integration Testing (System Validation)
-
-```bash
-# Verify public accessibility without casting
-# Create a simple test file:
-cat > test-public-api.test.ts << 'EOF'
-import { describe, it, expect } from 'vitest';
-import { Workflow } from '../src/core/workflow.js';
-
-describe('Workflow.isDescendantOf() - Public API', () => {
-  it('should be publicly accessible without casting', () => {
-    const root = new Workflow('root');
-    const child = new Workflow('child', { parent: root });
-
-    // This should work without (as any) cast
-    const result = child.isDescendantOf(root);
-
-    expect(result).toBe(true);
-  });
-
-  it('should return false for unrelated workflows', () => {
-    const tree1 = new Workflow('tree1');
-    const tree2 = new Workflow('tree2');
-
-    const result = tree1.isDescendantOf(tree2);
-
-    expect(result).toBe(false);
-  });
-
-  it('should return false when checking root against descendant', () => {
-    const root = new Workflow('root');
-    const child = new Workflow('child', { parent: root });
-
-    const result = root.isDescendantOf(child);
-
-    expect(result).toBe(false);
-  });
-});
-EOF
-
-# Run the test
-npm test test-public-api.test.ts
-
-# Expected: All new tests pass, proving public API accessibility
-```
-
-### Level 4: Creative & Domain-Specific Validation
-
-```bash
-# Manual validation of JSDoc visibility
-
-# 1. Generate TypeScript declaration files
-npx tsc --declaration --emitDeclarationOnly
-
-# 2. Check the generated .d.ts file
-cat src/core/workflow.d.ts | grep -A 10 "isDescendantOf"
-
-# Expected output should show:
-#   isDescendantOf(ancestor: Workflow): boolean;
-# (without private keyword)
-
-# 3. Verify IDE documentation
-# Open src/core/workflow.ts in VS Code
-# Hover over a workflow instance and verify isDescendantOf appears in autocomplete
-# Call the method and verify JSDoc tooltip shows documentation
-
-# 4. Security documentation validation
-cat plan/.../introspection-security-guide.md | grep -A 20 "Threat 5"
-
-# Expected: New Threat 5 section present with isDescendantOf documentation
-
-# 5. Verify no information disclosure beyond existing APIs
-# (This is conceptual - no automated test)
-# Review that isDescendantOf only returns boolean (true/false)
-# Compare with existing public APIs:
-# - workflow.parent: Returns full Workflow reference
-# - workflow.children: Returns array of Workflow references
-# - workflow.getNode(): Returns WorkflowNode with full tree, logs, events, state
-#
-# Conclusion: isDescendantOf exposes LESS information than existing APIs
-```
-
----
-
-## Final Validation Checklist
-
-### Technical Validation
-
-- [ ] `isDescendantOf()` changed from `private` to `public` at line 162
-- [ ] JSDoc documentation added with `@warning` tag
-- [ ] JSDoc includes `@param`, `@returns`, `@throws`, `@example` tags
-- [ ] TypeScript compilation succeeds: `npm run build`
-- [ ] All tests pass: `npm test`
-- [ ] No breaking changes to existing functionality
-- [ ] Security documentation updated with isDescendantOf section
-
-### Feature Validation
-
-- [ ] Method is publicly callable without `(as any)` cast
-- [ ] JSDoc `@warning` explains topology information disclosure
-- [ ] JSDoc references that `parent`/`children` are already public
-- [ ] Examples show practical usage patterns
-- [ ] Error handling documented (`@throws` for cycle detection)
-- [ ] Time/space complexity documented (O(d))
-
-### Code Quality Validation
-
-- [ ] Follows existing JSDoc patterns from `attachChild()` method
-- [ ] Uses markdown formatting consistent with codebase
-- [ ] Implementation logic unchanged (minizes risk)
-- [ ] No new dependencies added
-- [ ] No performance impact (method already tested and optimized)
-
-### Documentation & Deployment
-
-- [ ] Security guide updated (`introspection-security-guide.md`)
-- [ ] Threat 5 section added with mitigation patterns
-- [ ] References to existing public APIs (`parent`, `children`)
-- [ ] Application-level security responsibility documented
-- [ ] Semantic versioning impact noted (MAJOR version bump required)
-
----
-
-## Anti-Patterns to Avoid
-
-- **Don't** change the implementation logic - only visibility and documentation
-- **Don't** add unnecessary parameter validation if codebase doesn't use it elsewhere
-- **Don't** forget to document that `parent`/`children` are already public
-- **Don't** use recursive implementation (current iterative is stack-safe)
-- **Don't** skip the `@warning` tag - this is security-sensitive API
-- **Don't** modify existing tests - they should pass without changes
-- **Don't** forget Semantic Versioning implications (MAJOR bump required)
-- **Don't** make the method async - it's synchronous and should stay that way
-- **Don't** add depth limit parameter - S1 research didn't recommend it
-- **Don't** rename the method - keep `isDescendantOf` for consistency
-
----
-
-## Appendix: Implementation Reference
-
-### Current Implementation (Before Change)
-
-```typescript
-// File: src/core/workflow.ts, lines 152-180
-
-/**
- * Check if this workflow is a descendant of the given ancestor workflow
- * Traverses the parent chain upward looking for the ancestor reference
- * Uses visited Set to detect cycles during traversal
- *
- * @private
- * @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
- */
-private 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 false;
-}
-```
-
-### Proposed Implementation (After Change)
-
-```typescript
-// File: src/core/workflow.ts, lines 152-190 (proposed)
-
-/**
- * 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 false;
-}
-```
-
-### Security Documentation Addition
-
-```markdown
-# Add to: plan/001_d3bb02af4886/docs/research/general/introspection-security-guide.md
-# Location: After Threat 4 (Denial of Service), before Implementation Checklist
-
-### Threat 5: Topology Exposure via isDescendantOf
-
-**Attack Scenario:**
-```
-Attacker → Calls workflow.isDescendantOf(suspectWorkflow)
-         → Learns hierarchy relationship between workflows
-         → Maps workflow tree structure
-         → Extracts business intelligence from topology
-```
-
-**Risk Level:** LOW (same as current exposure)
-
-**Rationale:**
-- `parent` and `children` properties are already public
-- `getNode()` exposes full tree structure
-- `isDescendantOf()` only provides convenience, not new information
-- Attacker can already traverse tree manually
-
-**Affected Method:** `Workflow.isDescendantOf()` (newly public)
-
-**Mitigation:**
-1. **Application-Level Access Control** - If exposing workflows via API:
-   ```typescript
-   // Validate user has permission to access workflow
-   if (!user.canAccessWorkflow(workflowId)) {
-     throw new Error('Unauthorized');
-   }
-   // Only then allow isDescendantOf calls
-   ```
-
-2. **Filter Hierarchy Information** - For unauthenticated users:
-   ```typescript
-   // Return filtered view without hierarchy
-   const filteredWorkflow = {
-     id: workflow.id,
-     name: workflow.name,
-     // Omit parent, children, isDescendantOf
-   };
-   ```
-
-3. **Audit Topology Access** - Log calls to isDescendantOf:
-   ```typescript
-   auditLog.log({
-     timestamp: Date.now(),
-     userId: user.id,
-     action: 'isDescendantOf',
-     workflowId: workflow.id,
-     ancestorId: ancestor.id
-   });
-   ```
-
-**Recommendation:** Document that applications should implement access control
-if exposing workflows via APIs. The library itself provides no built-in security.
-```
-
----
-
-## Confidence Score
-
-**One-Pass Implementation Success Likelihood**: **9/10**
-
-**Rationale**:
-- S1 research and recommendation are comprehensive and clear
-- Implementation is straightforward (one keyword change + documentation)
-- Existing tests already cover the functionality (25+ test cases)
-- No logic changes required, minimizing risk
-- Clear documentation patterns exist in codebase to follow
-- Security implications are well-understood and documented
-
-**Risk Mitigation**:
-- Comprehensive JSDoc with security warning prevents misuse
-- Security documentation update addresses information disclosure
-- All changes are backward compatible (private → public only adds capability)
-- Existing test suite provides safety net
-
----
-
-**PRP Version**: 1.0
-**Last Updated**: 2026-01-12
-**Status**: Ready for Implementation