feat(flow): add subflow() DSL node for nested flow composition

[jafreck]

Summary

Add a first-class subflow() DSL node to @cadre-dev/framework/flow that allows composing a child FlowDefinition as a single node in a parent flow. This eliminates the need to manually instantiate FlowRunner inside a step's run() function.

Usage

const analysisFlow = defineFlow<{ issueNumber: number }>('analysis', [
  step({ id: 'scan', input: fromContext('issueNumber'), run: (_ctx, num) => ({ files: ['src/index.ts'], issue: num }) }),
]);

const pipeline = defineFlow<{ issue: number }>('pipeline', [
  step({ id: 'prepare', run: () => ({ ready: true }) }),
  subflow({
    id: 'run-analysis',
    flow: analysisFlow,
    contextMap: (ctx) => ({ issueNumber: ctx.context.issue }),
    dependsOn: ['prepare'],
  }),
]);

Changes

• types.ts: New FlowSubflowNode interface with flow, contextMap, and optional runnerOptions; added to FlowNode union
• dsl.ts: New subflow() builder function
• runner.ts: case 'subflow' handler that delegates to a child FlowRunner, propagates abort signals, returns { flowId, status, outputs }; updated indexNodes, validateDependsOnRefs (subflow nodes are opaque)
• contracts.ts: Updated indexFlow — subflow nodes are opaque to parent contract validation
• index.ts: Exported subflow and FlowSubflowNode
• flow-dsl.md: Documentation section with usage example

Design Decisions

• Opaque boundary: Child step IDs are scoped to the child flow. Parent sees { flowId, status, outputs }. No ID collisions.
• contextMap: Explicit bridge from parent to child context — no implicit sharing.
• Thunk support: flow accepts FlowDefinition | (ctx) => FlowDefinition for lazy/dynamic resolution.
• Abort propagation: Parent abort signal forwarded to child runner automatically.
• Error propagation: Child failures bubble up to the parent.

Tests

• 8 integration tests in subflow.test.ts
• 3 DSL unit tests in dsl.test.ts
• Public API contract test updated
• All 3768 tests pass

[codecov]

Codecov Report

❌ Patch coverage is 98.57651% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.25%. Comparing base (1199865) to head (c90adc1).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/framework/__tests__/flow/subflow.test.ts	99.04%	2 Missing ⚠️
packages/framework/src/flow/runner.ts	92.85%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #405      +/-   ##
==========================================
+ Coverage   91.12%   91.25%   +0.12%     
==========================================
  Files         212      213       +1     
  Lines       22250    22531     +281     
  Branches     3502     3528      +26     
==========================================
+ Hits        20275    20560     +285     
+ Misses       1928     1923       -5     
- Partials       47       48       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.