106 lines
4.8 KiB
Markdown
106 lines
4.8 KiB
Markdown
# 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 `StepKind`s **nest** — `Parallel` inside `Conditional` inside
|
||
`SubWorkflow` — and the concurrency contract still holds;
|
||
- a version bump that retains `StepId`s 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 `StepId`s; 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 `StepId`s; 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](../../../rust-agentic-sys.md) §4, §5.3 ·
|
||
[rust-agentic-task.md](../../../rust-agentic-task.md)
|