Validate submit root is a graph with --skip-validation bypass

[arseniy-pplx]

Summary

tangle sdk pipeline-runs submit builds an API submit payload from root_task.componentRef.spec and, until now, submitted whatever root shape the spec resolved to. A bare-container root (implementation.container) is accepted by the API but cannot run under current orchestrators, which require a graph root (implementation.graph) — the run later fails server-side with no local signal.

This change validates the resolved root locally, before any network call, and fails fast with an actionable message when the root is a bare container. An explicit opt-out preserves forward compatibility and advanced testing.

What changed

• Default validation: submit (and --dry-run) now reject a bare-container root before contacting the API, with a message that names the graph-root requirement and the bypass flag.
• Correct canonical target: the check runs after hydration/resolution against the canonical submit spec (root_task.componentRef.spec), so valid graph pipelines and resolved component references are not falsely rejected. Graph-root behavior is unchanged.
• Narrow check: validation is a focused root-shape check (graph vs. bare container) and does not run the full authoring validator, so unrelated validation cannot alter submit compatibility. Specs without an implementation mapping, or without a container root, are left for the API to validate.
• Explicit bypass: --skip-validation (and a matching skip_validation config key) bypass only this root-shape check and submit the body unchanged. Parsing, hydration, and security checks still run. The config value must be a real boolean; anything else fails with an invalid-config error.
• Single choke point: the check is threaded through prepare_submit_payload_from_spec, which backs both the dry-run and real-submit paths, while leaving the prepared-body escape hatches untouched.
• README updated to document the requirement and the bypass.

Test plan

• Bare-container root is rejected before any client call (submit and dry-run)
• Rejection message names the graph requirement and --skip-validation
• --skip-validation submits the bare body unchanged and reaches the client
• Graph root accepted by default; graph pipeline with a container task accepted
• skip_validation honored via config file; non-boolean config value rejected
• Root check does not trigger unrelated authoring validation
• uv run --frozen pytest -q (pre-existing unrelated failures only), uv build, CLI smoke test

---

🤖 Generated by Computer