feat: asymmetric handler signatures for simpler flow composition

[jumski]

Asymmetric Handler Signatures for Improved Flow Composition

This PR introduces asymmetric handler signatures, removing the run key from step inputs to enable cleaner functional composition and prepare the foundation for subflows.

Key Changes

• Root steps: Now receive flow input directly as first parameter (flowInput, ctx) => ...
• Dependent steps: Now receive only dependency outputs as first parameter (deps, ctx) => ...
• Flow input access: In dependent steps, access flow input via ctx.flowInput

Benefits

• Enables functional composition between flows
• Simplifies type definitions
• Prepares for future subflow functionality

Documentation

Added comprehensive migration guide with examples showing how to update:

• Root steps
• Dependent steps (with and without flow input access)
• Map steps

The guide includes step-by-step instructions for safely upgrading production deployments.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9ea84a2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@pgflow/core	Minor
@pgflow/dsl	Minor
@pgflow/client	Minor
@pgflow/edge-worker	Minor
pgflow	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jumski]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: make flowInput lazy-loaded to prevent data duplication in map steps #560
• feat: asymmetric handler signatures for simpler flow composition #559 👈 (View in Graphite)
• refactor: simplify step input structure by removing run key and using context.flowInput #558
• refactor: rename input parameters to flowInput and deps for clarity #557
• refactor: change step handler input to use asymmetric pattern for better type safety #556
• feat: add flow_input to StepTaskRecord and context objects #555
• feat: add flow_input field to step_task_record for direct access to original input #554
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 9ea84a2

Command	Status	Duration	Result
nx run edge-worker:test:integration	✅ Succeeded	3m 51s	View ↗
nx run core:pgtap	✅ Succeeded	1m 39s	View ↗
nx run client:e2e	✅ Succeeded	1m 9s	View ↗
nx run edge-worker:e2e	✅ Succeeded	37s	View ↗
nx affected -t verify-exports --base=origin/mai...	✅ Succeeded	3s	View ↗
nx run cli:e2e	✅ Succeeded	4s	View ↗
nx affected -t build --configuration=production...	✅ Succeeded	3s	View ↗
nx affected -t lint typecheck test --parallel -...	✅ Succeeded	27s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-12-24 12:26:26 UTC

[github-actions]

🔍 Preview Deployment: Website

✅ Deployment successful!

🔗 Preview URL: https://pr-559.pgflow.pages.dev

📝 Details:

• Branch: 12-24-add-changeset-and-news-for-assymetric-handlers
• Commit: 73f5c89f7a7692eebdb14ec76def8a31b91804ec
• View Logs

_Last updated: _