poimen/tasks/T3.7-p3-composition-gate.md

T3.7 — P3 composition gate

Field	Value
Phase	P3 — Workflow as data
Size	M — 1 to 3 days
Status	Not started
Flags	gate
Spec	inlined below
Blocks	P4

Goal

Prove the IR, the format plugins, validation, StepId stability, the interpreter and version pinning compose — and that format is genuinely interchangeable.

Phase gate criterion: a user-authored YAML workflow runs with no framework recompile.

Facts (inlined — no spec read needed)

• The workflow is data, not code. Users define workflows in their own format and version them; the framework executes and grades them without recompiling.
• Validation and canonicalization live in the kernel and run on the IR, so a new format inherits every check without reimplementing one. That claim is only proven by running the same validation suite against a format the kernel has never seen.
• The composition properties no single P3 task owns:
  • the same workflow in any format produces the same WorkflowVersion and the same episode;
  • all five StepKinds nest — Parallel inside Conditional inside SubWorkflow — and the concurrency contract still holds;
  • a version bump that retains StepIds keeps credit attributable across the bump (T3.4), while the running run stays pinned (T3.6).
• Recursion depth is bounded by the kernel and cycles are detected at load, not at execution — including cycles that only appear through a nested composition.

Steps

1. Author one non-trivial reference workflow exercising all five step kinds, nested at least two levels, with loops at their declared bounds.
2. Express it in YAML, in JSON, and in the third format from T3.2's external crate.
3. Assert identical WorkflowVersion and identical episode structure across all three.
4. Run the full T3.3 validation suite against all three formats.
5. Bump the workflow version retaining StepIds; assert credit keys survive and in-flight runs stay pinned.
6. Make this the required CI job gating P4.

Acceptance

• The reference workflow, expressed in three formats, produces one WorkflowVersion and one episode structure.
• The validation suite passes identically against all three formats.
• No framework recompile is needed to run a user-authored workflow.

Verify

Harness: the reference workflow as a committed fixture in three formats; T3.2's third-format crate living outside the workspace.

Integration test — tests/it_p3_composition.rs:

1. Format interchange: parse all three; assert equal WorkflowVersion, then run all three and assert equal episode structure with volatile fields normalized against an enumerated list.
2. Nesting: assert the nested Parallel-inside-Conditional-inside- SubWorkflow executes correctly, that fan-out is concurrent, and that cancelling the run terminates every nested branch.
3. Serial spine under nesting: assert no two non-Parallel steps overlap, even across the sub-workflow boundary.
4. Validation parity: run every malformed fixture from T3.3 through all three formats; assert the same ValidationError variant each time. A format producing a different error has forked the rules.
5. Cycle through composition: build a cycle that exists only via a nested sub-workflow. Assert it is rejected at load.
6. Version bump: bump retaining StepIds; assert the added/removed/retained report is recorded, and that a run started before the bump completes on the pinned version.
7. Recompile check: add a fourth workflow file at runtime, in a directory the test writes to, and run it. Assert no rebuild occurred — the binary under test is the one built before the file existed.
8. Regression: re-run P0–P2 gates and all P3 suites.

Command: cargo test -p workflow --test it_p3_composition && cargo test --manifest-path third-format-crate/Cargo.toml

False pass:

• Step 1 with a trivial single-step workflow. Every format handles that; the divergence lives in nesting and in optional fields.
• Step 4 omitted: a format doing its own validation passes the equal-version test and silently accepts workflows the kernel would reject.
• Step 7 conflated with "the test passes". The claim is no recompile — assert the workflow file was created after the binary, not just that it ran.
• Running the third format from inside the workspace, where it reaches internals.

Traps

• Letting the reference workflow shrink over time as steps are removed to make a test pass. Its coverage is the point; assert its step-kind coverage explicitly.

---

Background (not required to do this task): rust-agentic-sys.md §4, §5.3 · rust-agentic-task.md