groundswell 0.0.1 → 0.0.2

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

@@ -0,0 +1,520 @@
+# Product Requirement Prompt (PRP): Evaluate Use Cases for Public isDescendantOf API
+
+**Work Item**: P1.M3.T4.S1 - Evaluate use cases for public isDescendantOf API
+**PRD Reference**: Issue 9 - Steps Not in Tree Structure (Bug Report Note)
+**Implementation Target**: src/core/workflow.ts:162-180
+
+---
+
+## Goal
+
+**Feature Goal**: Research and document whether the `isDescendantOf()` method should be exposed as a public API, providing a clear recommendation with supporting evidence and rationale.
+
+**Deliverable**: A comprehensive recommendation document (`RECOMMENDATION.md`) that includes:
+1. Clear recommendation (make public vs keep private)
+2. Rationale based on user needs and use cases
+3. Security implications analysis
+4. Industry comparison with other workflow engines
+5. Implementation guidance if approved
+
+**Success Definition**: The recommendation document enables P1.M3.T4.S2 to either implement the public API or document the rationale for keeping it private, with full confidence that all factors have been considered.
+
+## User Persona
+
+**Target User**: Developer implementing P1.M3.T4.S2 (public API implementation) and Technical Lead making the final decision
+
+**Use Case**: Making an informed decision about exposing `isDescendantOf()` as a public API based on comprehensive research
+
+**User Journey**:
+1. Review current implementation and usage patterns
+2. Understand user needs for ancestry checking
+3. Evaluate security implications
+4. Compare with industry practices
+5. Make informed recommendation
+6. Implement or document decision
+
+**Pain Points Addressed**:
+- Uncertainty about whether external ancestry checks are useful
+- Lack of data on user needs for hierarchy navigation
+- Security concerns about exposing workflow topology
+- Need for industry context to inform decision
+
+## Why
+
+- **User Experience**: Introspection tools show users want to navigate workflow hierarchies
+- **API Ergonomics**: `isDescendantOf()` provides a cleaner interface than manual tree traversal
+- **Industry Alignment**: Need to understand whether this is standard practice or anti-pattern
+- **Security**: Must evaluate information disclosure risks before exposing internal APIs
+- **Architectural Intent**: Determine if this is an implementation detail or useful feature
+
+## What
+
+### Success Criteria
+
+- [ ] Recommendation document created at `P1M3T4S1/RECOMMENDATION.md`
+- [ ] Current implementation documented (src/core/workflow.ts:162-180)
+- [ ] User needs and use cases catalogued from codebase analysis
+- [ ] Security implications assessed with risk level
+- [ ] Industry comparison completed with specific URLs and examples
+- [ ] Clear recommendation provided with implementation guidance
+
+---
+
+## All Needed Context
+
+### Context Completeness Check
+
+_This PRP passes the "No Prior Knowledge" test - someone unfamiliar with the codebase would have everything needed to complete this research task successfully._
+
+### Documentation & References
+
+```yaml
+# 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: Only used internally in attachChild() for circular reference prevention
+
+# CRITICAL - Current Usage
+- file: src/core/workflow.ts
+  why: Single usage site at line 293 in attachChild() method
+  pattern: Circular reference detection before attaching child workflows
+  gotcha: Throws descriptive error message explaining circular reference
+
+# CRITICAL - Introspection Tools (User Needs Evidence)
+- file: src/tools/introspection.ts
+  why: Public introspection tools showing user needs for hierarchy navigation
+  pattern: Tools like read_ancestor_chain, inspect_current_node provide hierarchy info
+  gotcha: These tools already expose MORE hierarchy information than isDescendantOf would
+
+# CRITICAL - Examples Demonstrating User Needs
+- file: examples/examples/10-introspection.ts
+  why: Demonstrates read_ancestor_chain tool with "What's above me?" use case
+  pattern: Users want to understand their position in workflow hierarchy
+  gotcha: Shows real-world need for ancestry checking
+
+- file: examples/examples/03-parent-child.ts
+  why: Shows users accessing workflow hierarchy via children and node properties
+  pattern: Manual tree traversal to display workflow structure
+  gotcha: Users already doing manual ancestry checking via parent/children properties
+
+# CRITICAL - Public Properties Already Exposing Hierarchy
+- file: src/core/workflow.ts:49-52
+  why: The parent and children properties are already PUBLIC
+  pattern: public parent: Workflow | null; public children: Workflow[];
+  gotcha: Any code with Workflow reference can already traverse entire tree
+
+# CRITICAL - WorkflowNode Interface
+- file: src/types/workflow.ts:20-37
+  why: Defines what data is exposed via getNode() method
+  pattern: Contains parent, children, logs, events, stateSnapshot fields
+  gotcha: getNode() already exposes full tree structure with potentially sensitive data
+
+# REFERENCE - Security Guide
+- docfile: plan/001_d3bb02af4886/docs/research/general/introspection-security-guide.md
+  why: Comprehensive security analysis for introspection and hierarchy exposure
+  section: Threat models and mitigation patterns for topology information
+  gotcha: Groundswell is a library - security is application's responsibility
+
+# REFERENCE - Bug Fix Context
+- docfile: plan/001_d3bb02af4886/docs/bugfix/bugfix_README.md
+  why: Issue #9 context about "Steps Not in Tree Structure"
+  section: Lines 101-105 describe Issue #9 as intentional design decision
+  gotcha: isDescendantOf note comes from bug report analysis
+
+# EXTERNAL RESEARCH - Workflow Engines
+- docfile: P1M3T4S1/research/external_workflow_engines_research.md
+  why: Comprehensive comparison of Airflow, Temporal, Prefect, Dagster, GitHub Actions, AWS Step Functions
+  section: API Exposure Matrix shows NO major system exposes public descendant checking
+  critical: Groundswell would be UNIQUE in exposing isDescendantOf() as public API
+
+# EXTERNAL RESEARCH - Security Implications
+- docfile: P1M3T4S1/research/security_implications_analysis.md
+  why: Detailed security analysis of information disclosure risks
+  section: Comparison with existing public APIs shows NO new information exposed
+  critical: parent/children already public, getNode() already exposes full tree
+
+# DOCUMENTATION URLs
+- url: https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
+  why: Airflow's approach to task relationships (upstream/downstream terminology)
+  critical: Airflow uses get_upstream()/get_downstream() for immediate neighbors only
+
+- url: https://docs.temporal.io/develop/python/child-workflows
+  why: Temporal's child workflow approach (parent/child terminology)
+  critical: Temporal does NOT expose public ancestry checking APIs
+
+- url: https://docs.prefect.io/latest/concepts/dependencies/
+  why: Prefect's dependency model (upstream/downstream terminology)
+  critical: Prefect focuses on execution state, not topology queries
+```
+
+### Current Codebase Tree (relevant to isDescendantOf)
+
+```bash
+src/
+├── core/
+│   └── workflow.ts              # isDescendantOf at line 162-180 (private)
+│                                # 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
+    └── unit/
+        └── introspection-tools.test.ts    # Tests for ancestry navigation tools
+```
+
+### Known Gotchas of Our Codebase
+
+```typescript
+// CRITICAL: isDescendantOf is private - changing to public is a breaking API change
+// Must consider backward compatibility if any external code relies on privacy
+
+// 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: WorkflowNode includes potentially sensitive data:
+// - logs (may contain debugging info)
+// - events (may contain business logic)
+// - stateSnapshot (may contain @ObservedState fields with secrets)
+
+// CRITICAL: Introspection tools are already PUBLIC
+// read_ancestor_chain exposes MORE info than isDescendantOf would
+```
+
+---
+
+## Implementation Blueprint
+
+### Research Tasks (ordered by dependencies)
+
+```yaml
+Task 1: ANALYZE Current Implementation
+  - LOCATE: src/core/workflow.ts lines 162-180
+  - DOCUMENT: Exact implementation of isDescendantOf method
+  - IDENTIFY: Algorithm used (iterative traversal with visited Set)
+  - UNDERSTAND: Purpose (cycle detection in attachChild)
+  - OUTPUT: Implementation summary with code snippet
+
+Task 2: INVENTORY Current Usage Patterns
+  - SEARCH: All call sites of isDescendantOf in codebase
+  - ANALYZE: How it's used (only in attachChild for circular reference detection)
+  - VERIFY: Error messages and edge cases
+  - CHECK: Test coverage for isDescendantOf behavior
+  - OUTPUT: Usage inventory with file locations and line numbers
+
+Task 3: RESEARCH User Needs and Use Cases
+  - ANALYZE: Introspection tools (src/tools/introspection.ts)
+  - EXAMINE: Examples showing hierarchy navigation (examples/10-introspection.ts)
+  - SEARCH: Feature requests or issues asking for ancestry checking
+  - IDENTIFY: Patterns where users manually traverse parent chain
+  - OUTPUT: Use case inventory with specific examples
+
+Task 4: COMPARE with Existing Public APIs
+  - ANALYZE: What information is already exposed (parent, children, getNode())
+  - COMPARE: isDescendantOf vs existing APIs in terms of information disclosure
+  - EVALUATE: Whether isDescendantOf adds new capabilities
+  - ASSESS: Impact on security posture
+  - OUTPUT: Comparison matrix with risk assessment
+
+Task 5: RESEARCH Industry Practices
+  - INVESTIGATE: Apache Airflow, Temporal, Prefect, Dagster, GitHub Actions, AWS Step Functions
+  - DOCUMENT: How each system handles ancestry/descendant checking
+  - ANALYZE: Terminology patterns (parent/child vs upstream/downstream)
+  - IDENTIFY: Security patterns for topology exposure
+  - OUTPUT: Industry comparison with specific URLs and examples
+
+Task 6: EVALUATE Security Implications
+  - ANALYZE: What information isDescendantOf reveals
+  - COMPARE: With existing public APIs (parent, children, getNode())
+  - ASSESS: Information disclosure risk level
+  - IDENTIFY: Attack vectors (topology extraction, business intelligence)
+  - REVIEW: Existing security documentation (introspection-security-guide.md)
+  - OUTPUT: Security assessment with risk level and mitigations
+
+Task 7: MAKE Final Recommendation
+  - SYNTHESIZE: Findings from all research tasks
+  - EVALUATE: Pros and cons of making public vs keeping private
+  - DECIDE: Clear recommendation with supporting rationale
+  - PROVIDE: Implementation guidance if approved
+  - PROVIDE: Documentation rationale if not approved
+  - OUTPUT: RECOMMENDATION.md with clear decision and next steps
+```
+
+### Research Methodology & Key Questions
+
+```typescript
+// Question 1: What is isDescendantOf and how does it work?
+// ANSWER: Private method checking if this workflow is a descendant of given ancestor
+// IMPLEMENTATION: Iterative traversal up parent chain with visited Set for cycle detection
+
+// Question 2: Where is it currently used?
+// ANSWER: Only one place - attachChild() method at line 293
+// PURPOSE: Prevent circular references by checking if child is an ancestor
+
+// Question 3: Do users need this functionality?
+// ANSWER: Evidence suggests YES - introspection tools show hierarchy navigation needs
+// EVIDENCE:
+// - read_ancestor_chain tool: "What's above me?"
+// - inspect_current_node tool: Shows depth and parent info
+// - Examples show manual tree traversal to display hierarchy
+
+// Question 4: Does it expose new security risks?
+// ANSWER: NO - parent and children are already public
+// COMPARISON:
+// - workflow.parent: Public (direct parent reference)
+// - workflow.children: Public (all immediate children)
+// - workflow.getNode(): Public (full tree with logs, events, state)
+// - isDescendantOf(): Would provide convenience, not new information
+
+// Question 5: What do other workflow engines do?
+// ANSWER: NO major system exposes public ancestry checking API
+// FINDINGS:
+// - Airflow: get_upstream()/get_downstream() (immediate only)
+// - Temporal: No public API
+// - Prefect: No public API
+// - Dagster: Indirect via AssetSelection
+// - Groundswell: Would be UNIQUE in exposing this
+```
+
+### Decision Framework
+
+```yaml
+EVALUATION CRITERIA:
+  User Value:
+    - High: Provides clean API for common hierarchy queries
+    - Evidence: Introspection tools show user need
+    - Score: 8/10
+
+  Security Risk:
+    - Low: No new information beyond existing public APIs
+    - parent/children already public
+    - Score: 2/10 (10 = highest risk)
+
+  Implementation Cost:
+    - Very Low: Just change private to public, add documentation
+    - Already battle-tested (25+ test cases)
+    - Score: 1/10 (10 = highest cost)
+
+  Industry Alignment:
+    - Neutral: No industry standard, but no anti-pattern either
+    - Would be differentiator (no major system has this)
+    - Score: 5/10
+
+  Maintenance Burden:
+    - Low: Simple method with minimal surface area
+    - Already stable and tested
+    - Score: 2/10
+
+DECISION MATRIX:
+  KEEP PRIVATE:
+    Pros:
+      - Follows industry pattern (most systems keep this internal)
+      - Minimal API surface area
+      - No documentation burden
+    Cons:
+      - Users must manually traverse parent chain
+      - Less ergonomic API
+
+  MAKE PUBLIC:
+    Pros:
+      - Cleaner API for hierarchy queries
+      - Aligns with introspection tool philosophy
+      - Already battle-tested
+      - No new security risk
+    Cons:
+      - Larger API surface area
+      - Documentation required
+      - Different from industry (but not anti-pattern)
+
+RECOMMENDATION: MAKE PUBLIC with safeguards
+```
+
+### Integration Points
+
+```yaml
+CODE CHANGES (if approved):
+  - modify: src/core/workflow.ts
+  - change: Line 162 from `private isDescendantOf` to `public isDescendantOf`
+  - add: JSDoc documentation with security warning
+  - preserve: All existing functionality and tests
+
+DOCUMENTATION CHANGES:
+  - add: Security warning about topology exposure
+  - update: API documentation with examples
+  - reference: Introspection tools as related functionality
+
+SECURITY DOCUMENTATION:
+  - update: introspection-security-guide.md with isDescendantOf section
+  - document: Application-level access control requirements
+  - provide: Examples of safe usage patterns
+```
+
+---
+
+## Validation Loop
+
+### Level 1: Research Completeness (Immediate Feedback)
+
+```bash
+# Verify all research tasks completed
+echo "Checking research artifacts..."
+ls -la P1M3T4S1/research/
+
+# Expected files:
+# - external_workflow_engines_research.md (comprehensive industry comparison)
+# - security_implications_analysis.md (security risk assessment)
+
+# Validate research covers all required areas:
+# - Current implementation: YES (workflow.ts:162-180)
+# - Usage patterns: YES (only attachChild at line 293)
+# - User needs: YES (introspection tools, examples)
+# - Security: YES (comparison with existing APIs)
+# - Industry: YES (6 major systems analyzed)
+
+# Expected: All research artifacts present and comprehensive
+```
+
+### Level 2: Decision Validation (Peer Review)
+
+```bash
+# Review recommendation document for:
+cat P1M3T4S1/RECOMMENDATION.md
+
+# Validate inclusion of:
+# 1. Clear recommendation (public vs private)
+# 2. Rationale with supporting evidence
+# 3. Security assessment with risk level
+# 4. Industry comparison summary
+# 5. Implementation guidance or documentation rationale
+
+# Expected: Recommendation is clear, well-supported, and actionable
+```
+
+### Level 3: Cross-Reference Validation
+
+```bash
+# Verify recommendation aligns with:
+# - Bug fix task specification (bug_fix_tasks.json)
+grep -A 5 "P1.M3.T4.S1" plan/001_d3bb02af4886/bug_fix_tasks.json
+
+# - Security documentation
+ls plan/001_d3bb02af4886/docs/research/general/introspection-security-guide.md
+
+# - Related work items (P1.M3.T4.S2 implementation task)
+# Verify S2 can use this recommendation for implementation
+
+# Expected: Recommendation addresses all task requirements
+```
+
+### Level 4: Implementation Readiness (If Approved)
+
+```bash
+# If recommending public API, validate:
+# 1. Implementation location is clear (src/core/workflow.ts:162)
+# 2. Code change is minimal (private -> public)
+# 3. Documentation requirements are defined
+# 4. Test coverage already exists (25+ test cases)
+
+# Check existing test coverage
+grep -r "isDescendantOf" src/__tests__/ --include="*.test.ts" | wc -l
+
+# Expected: High confidence that S2 can implement without additional research
+```
+
+---
+
+## Final Validation Checklist
+
+### Research Validation
+
+- [ ] Current implementation fully documented with code examples
+- [ ] All usage sites identified and analyzed
+- [ ] User needs catalogued with specific examples
+- [ ] Security implications assessed with risk level
+- [ ] Industry comparison completed with specific URLs
+- [ ] Decision framework applied with scoring
+
+### Recommendation Validation
+
+- [ ] Clear recommendation provided (public or private)
+- [ ] Rationale supported by research evidence
+- [ ] Security implications addressed
+- [ ] Implementation guidance included (if approved)
+- [ ] Documentation rationale included (if not approved)
+- [ ] Next steps clearly defined for P1.M3.T4.S2
+
+### Documentation Validation
+
+- [ ] RECOMMENDATION.md created at P1M3T4S1/RECOMMENDATION.md
+- [ ] All research artifacts stored in P1M3T4S1/research/
+- [ ] External research includes specific URLs
+- [ ] Security analysis includes risk assessment
+- [ ] Code snippets include file paths and line numbers
+
+### Quality Validation
+
+- [ ] Research passes "No Prior Knowledge" test
+- [ ] Recommendation is actionable and unambiguous
+- [ ] All sources cited with specific references
+- [ ] Decision framework is transparent and reproducible
+- [ ] Conflicts in evidence are acknowledged and addressed
+
+---
+
+## Anti-Patterns to Avoid
+
+- **Don't** make recommendation without comprehensive research
+- **Don't** ignore security implications (even if low risk)
+- **Don't** overlook that parent/children are already public
+- **Don't** forget about introspection tools (already expose hierarchy)
+- **Don't** assume user needs without evidence from codebase
+- **Don't** compare with industry without specific URLs and examples
+- **Don't** provide ambiguous recommendation (must be clear: public or private)
+- **Don't** skip implementation guidance (S2 needs to know exactly what to do)
+
+---
+
+## Appendix: Research Artifacts
+
+### Generated Documents
+
+```bash
+P1M3T4S1/
+├── PRP.md                           # This document
+├── RECOMMENDATION.md                # Final recommendation (TO BE CREATED)
+└── research/
+    ├── external_workflow_engines_research.md      # Industry comparison (COMPLETED)
+    └── security_implications_analysis.md          # Security assessment (COMPLETED)
+```
+
+### Key Findings Summary
+
+**Current State:**
+- `isDescendantOf()` is private at src/core/workflow.ts:162-180
+- Only used in attachChild() for circular reference detection
+- Battle-tested with 25+ test cases
+
+**User Needs:**
+- Introspection tools show hierarchy navigation is important
+- Examples show users manually traversing parent chain
+- read_ancestor_chain tool: "What's above me?"
+
+**Security:**
+- parent and children properties are already PUBLIC
+- getNode() already exposes full tree structure
+- isDescendantOf would NOT expose new information
+- Risk level: LOW (same as current exposure)
+
+**Industry:**
+- NO major workflow engine exposes public ancestry checking
+- Groundswell would be UNIQUE in this regard
+- Not an anti-pattern, just different from industry
+
+**Recommendation:** Make public with safeguards (see RECOMMENDATION.md for details)