feat(java): sub-workflow steps

[pratyush618]

Adds nested workflows to the Java SDK: a step can submit another Workflow
as a child run and complete (or fail) when that child finalizes.

API

• Step.Builder.subWorkflow(Workflow child) — turns a step into a sub-workflow node.
• Workflow.subWorkflow(name, child, deps...) builder shortcut.
• Validation: a sub-workflow step can't also be a gate / fan-out / fan-in.

Mechanics (host tracker, no new Rust seam)

• Sub-workflow nodes are deferred at submit (like gates/fan-out), serialized via
  a ChildSpec carrying the child's steps JSON + per-node payloads + deferred set.
• On promotion the tracker submits the child run (reusing the existing
  submitWorkflow(..., parentRunId, parentNodeName) seam) and parks the parent
  node RUNNING.
• When the child run reaches a terminal state, finalizeIfTerminal resolves the
  parent node via resolveWorkflowGate(succeeded) and advances the parent —
  same in-process resolution path gates use. No event bus, no Rust change.

Tests

WorkflowSubWorkflowTest covers a child run completing the parent node and a
failing child failing the parent.

Stacked on #332 (conditions); rebased onto master now that it merged.

Summary by CodeRabbit

• New Features

  • Added nested sub-workflow support for Java workflows via a new subWorkflow step option.
  • Parent workflows now run-and-wait on child workflows, with support for nested execution graphs.

• Bug Fixes

  • Improved sub-workflow run tracking, including correct per-run payload handling (with Base64-encoded embedded payloads).
  • Updated deferred-node behavior and validation to better reflect sub-workflow control semantics.

• Tests

  • Added end-to-end sub-workflow tests covering success, failure/skip behavior, and submit-time rejection cases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0bcacd9d-5155-434b-a073-53b4c9ed7727

📥 Commits

Reviewing files that changed from the base of the PR and between 3842dd2 and dab4f88.

📒 Files selected for processing (3)

• sdks/java/src/main/java/org/byteveda/taskito/DefaultTaskito.java
• sdks/java/src/main/java/org/byteveda/taskito/workflows/WorkflowTracker.java
• sdks/java/src/test/java/org/byteveda/taskito/WorkflowSubWorkflowTest.java

🚧 Files skipped from review as they are similar to previous changes (3)

• sdks/java/src/test/java/org/byteveda/taskito/WorkflowSubWorkflowTest.java
• sdks/java/src/main/java/org/byteveda/taskito/workflows/WorkflowTracker.java
• sdks/java/src/main/java/org/byteveda/taskito/DefaultTaskito.java

---

📝 Walkthrough

Walkthrough

Adds nested sub-workflow support to Taskito. Step, Workflow, and PlanNode gain sub-workflow fields and APIs; DefaultTaskito encodes child workflows with Base64 payloads; WorkflowTracker submits child runs, tracks parent links, and propagates child terminal state; tests cover success, failure, and invalid submission cases.

Changes

Sub-workflow feature

Layer / File(s)	Summary
Step, Workflow, and PlanNode contracts sdks/java/src/main/java/org/byteveda/taskito/workflows/Step.java, sdks/java/src/main/java/org/byteveda/taskito/workflows/Workflow.java, sdks/java/src/main/java/org/byteveda/taskito/workflows/PlanNode.java	Step gains a subWorkflow field, builder method, and validation; Workflow adds subWorkflow() and SUB_WORKFLOW_TASK; PlanNode accepts subWorkflow in JSON.
Sub-workflow encoding in DefaultTaskito sdks/java/src/main/java/org/byteveda/taskito/DefaultTaskito.java	stepSpec now emits subWorkflow data, encodeChild serializes child workflows and Base64 payloads, and deferred-node handling includes sub-workflows.
WorkflowTracker orchestration sdks/java/src/main/java/org/byteveda/taskito/workflows/WorkflowTracker.java	Sub-workflow successor promotion submits child runs, stores child payloads and parent links, resolves parent nodes on child completion, and cleans up child state.
Integration tests sdks/java/src/test/java/org/byteveda/taskito/WorkflowSubWorkflowTest.java	Tests cover child success continuing the parent, child failure skipping downstream work, and submission-time rejection for unsupported child steps.

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowTracker
  participant backend
  participant ChildRun
  WorkflowTracker->>WorkflowTracker: promote successor node (subWorkflow)
  WorkflowTracker->>backend: submitWorkflow(childSpec)
  backend-->>WorkflowTracker: childRunId
  WorkflowTracker->>WorkflowTracker: store childRunPayloads and childToParent
  ChildRun-->>WorkflowTracker: terminal state
  WorkflowTracker->>WorkflowTracker: resolveSubWorkflowParent(parentRunId, parentNodeName, state)
  WorkflowTracker->>WorkflowTracker: promote parent successors / finalize parent run

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• ByteVeda/taskito#332: Modifies the same workflow-step serialization and deferred-node handling path in DefaultTaskito and WorkflowTracker.

Poem

🐇 A tiny child workflow began to hop,
With payloads tucked safely in Base64 crop.
The parent watched closely, then carried on through,
When child steps were done, the tracker knew what to do.
Hop, hop — the workflow tree grew!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.74% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the main change: adding sub-workflow step support in the Java SDK.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/java-workflows-subworkflows

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@sdks/java/src/main/java/org/byteveda/taskito/DefaultTaskito.java`:
- Around line 479-503: encodeChild() currently serializes only step.payload
bytes and the wire condition string, so child workflows that rely on submit-time
payload injection via Workflow.stepAfter(...) or on condition(Condition) can
lose required runtime state. Update DefaultTaskito.encodeChild() to fail fast
when a child Step has payload == null or any non-wire condition metadata that
ChildSpec/tracker cannot preserve, using the existing encodeChild(), stepSpec(),
and deferredNodes() flow to locate the check. If support is intended, extend
ChildSpec and the tracker submission path to carry the missing payload/condition
metadata instead of silently dropping it.

In `@sdks/java/src/main/java/org/byteveda/taskito/workflows/WorkflowTracker.java`:
- Around line 286-299: The deferred payload registration in submitSubWorkflow()
is keyed by child.name, but lookup later flows through workflowName(runId), so
concurrent runs can overwrite each other and mix payload state. Update
WorkflowTracker to store child runtime/deferred payload state under the child
run id returned by backend.submitWorkflow (or another run-scoped key), and make
the deferred-node promotion path read from that run-scoped mapping instead of
the workflow name.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 120d76e7-4b3d-4158-84a2-4f0decc13e52

📥 Commits

Reviewing files that changed from the base of the PR and between 7b26819 and 3d5e76a.

📒 Files selected for processing (6)

• sdks/java/src/main/java/org/byteveda/taskito/DefaultTaskito.java
• sdks/java/src/main/java/org/byteveda/taskito/workflows/PlanNode.java
• sdks/java/src/main/java/org/byteveda/taskito/workflows/Step.java
• sdks/java/src/main/java/org/byteveda/taskito/workflows/Workflow.java
• sdks/java/src/main/java/org/byteveda/taskito/workflows/WorkflowTracker.java
• sdks/java/src/test/java/org/byteveda/taskito/WorkflowSubWorkflowTest.java