96 lines
3.9 KiB
Markdown
96 lines
3.9 KiB
Markdown
# T3.2 — `WorkflowFormat` trait + YAML and JSON
|
||
|
||
| Field | Value |
|
||
|---|---|
|
||
| Phase | P3 — Workflow as data |
|
||
| Size | M — 1 to 3 days |
|
||
| Status | Not started |
|
||
| Flags | — |
|
||
| Spec | inlined below |
|
||
| Blocks | — |
|
||
|
||
## Goal
|
||
|
||
Formats are plugins. Ship YAML and JSON; prove a third format needs no kernel
|
||
change.
|
||
|
||
## Facts (inlined — no spec read needed)
|
||
|
||
```rust
|
||
pub trait WorkflowFormat: Send + Sync {
|
||
fn extensions(&self) -> &[&str];
|
||
fn parse(&self, src: &[u8]) -> Result<WorkflowDef, ParseError>;
|
||
}
|
||
```
|
||
|
||
- A user wanting a DSL, Starlark, or a database row implements the trait.
|
||
- **Validation and canonicalization live in the kernel and run on the IR** (T3.1,
|
||
T3.3), so a new format inherits every check without reimplementing one. A
|
||
format that does its own validation has forked the rules.
|
||
- Because the version hash is over the canonical IR, the same workflow in two
|
||
formats must produce the same `WorkflowVersion` — that equality is the test
|
||
that the boundary is in the right place.
|
||
- Defaults ship working; every default is a port. A user who wants built-in
|
||
behaviour writes no code; a user who wants their own writes an impl, not a fork.
|
||
|
||
## Steps
|
||
|
||
1. Define the trait exactly as above. `parse` returns the IR and nothing else —
|
||
no side effects, no registration, no validation.
|
||
2. Implement `YamlFormat` and `JsonFormat` over `serde`. Both target the same IR
|
||
types from T3.1.
|
||
3. Build the format registry keyed by extension. Resolution is by extension, with
|
||
a clear error when two formats claim the same one.
|
||
4. Make `ParseError` carry position information where the format supplies it —
|
||
this is the only error type that legitimately knows about source text.
|
||
5. Write the same workflow in YAML and in JSON; assert equal `WorkflowVersion`.
|
||
6. In a **separate test crate**, implement a third trivial format (for example
|
||
TOML or a line-based DSL) against the public API only. If it needs anything
|
||
`pub(crate)`, the trait is short — fix the trait, not the test.
|
||
|
||
## Acceptance
|
||
|
||
- The same workflow expressed in both formats produces the same
|
||
`WorkflowVersion`.
|
||
- A third format added in a test crate needs **no kernel change**.
|
||
|
||
## Verify
|
||
|
||
**Harness:** a **separate test crate outside the workspace** depending only on
|
||
the published API — that crate's existence is the deliverable, not a convenience.
|
||
|
||
**Integration test** — `tests/it_format_equivalence.rs` plus
|
||
`third-format-crate/`:
|
||
1. Express one non-trivial workflow (all five `StepKind`s) in YAML and in JSON.
|
||
2. Parse both; assert identical `WorkflowVersion`.
|
||
3. Assert the parsed IRs are byte-identical after canonicalization.
|
||
4. In the external crate, implement a third format (TOML or a line DSL) against
|
||
the public API only. Build it. If it needs any `pub(crate)` item, the trait is
|
||
short — that is a finding, not a test workaround.
|
||
5. Register the third format and run the **same** validation suite (T3.3) against
|
||
it; assert it inherits every check with no new code.
|
||
6. Extension collision: register two formats claiming `.yaml`; assert a clear
|
||
error rather than last-one-wins.
|
||
|
||
**Command:** `cargo test -p workflow format_equivalence && cargo test --manifest-path third-format-crate/Cargo.toml`
|
||
|
||
**False pass:**
|
||
- The third-format crate living inside the workspace, where it can reach
|
||
internals. It then passes while the public API is unusable — which is the
|
||
entire thing being tested.
|
||
- Step 5 omitted: a format that does its own validation passes steps 1–4 and has
|
||
quietly forked the rules.
|
||
|
||
## Traps
|
||
|
||
- Format-specific validation creeping into `parse`. Two formats then disagree
|
||
about what is legal.
|
||
- Leaking `serde` types into the IR, which makes the third-format test need a
|
||
serde dependency it should not have.
|
||
|
||
---
|
||
|
||
Background (not required to do this task):
|
||
[rust-agentic-sys.md](../../../rust-agentic-sys.md) §1, §4.2 ·
|
||
[rust-agentic-task.md](../../../rust-agentic-task.md)
|