feat(workflow): define-subgraph command emitting define_subgraph op

[christian-byrne]

• Adds comfy workflow define-subgraph.
• Emits the cmp-compatible define_subgraph payload.
• Focused tests and static gates are green.

Full context for agent readers

What and why

Adds comfy workflow define-subgraph <workflow-file> <subgraph-definition-file> [--id <uuid>], following the command and op-building pattern in the sibling insert-workflow pull request.

The command performs only envelope shape and serialization checks, creates a new definition id when one is not supplied, and emits one define_subgraph op using the exact subgraph_id and subgraph_definition fields from the cmp contract pull request. It does not mutate the local workflow. This implements the CLI slice of the first-class subgraph technical design.

cmp owns semantic validation, application, replay, projection, and conflict handling. The CLI surfaces cmp's definition_conflict and unknown-node errors verbatim. Other op kinds reject definition payload fields. define_subgraph remains in the batchable vocabulary, matching cmp.

RED to GREEN evidence

RED:

7 failed in 0.64s
AttributeError: module 'comfy_cli.workflow_ops' has no attribute 'define_subgraph'

GREEN:

14 passed in 0.11s

The emit-only RED probes initially failed 4/4 (local mutation, semantic rejection, local replay, and command file writes). All now pass.

Gates

uv run ruff check .
All checks passed!

uv run ruff format --check comfy_cli/workflow_ops.py tests/comfy_cli/test_define_subgraph_op.py
2 files already formatted

uv run pytest -q <define-subgraph and neighbouring workflow-op test files>
99 passed in 0.29s

The full suite completed with 7,417 passing, 32 skipped, and 45 failures unrelated to this diff. The failures are concentrated in existing run/preflight tests that consume live cached object-info and two existing umask expectations; focused changed-area tests are green.

Vetoable decisions

• Keep --id optional: use the definition's existing string id, otherwise mint a UUID. A supplied --id must match an existing definition id.
• Mark define_subgraph batchable because the cmp contract adds it to BATCHABLE_OPS; the standalone command remains the explicit creation surface.
• Keep UUID and payload-id agreement checks as envelope shape validation; cmp owns all definition-content semantics and id-conflict handling.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[github-actions]

🔍 Cursor Review — Consolidated panel

Triggered by @christian-byrne.

Found 9 finding(s).

Severity	Count
🟠 High	2
🟡 Medium	3
🟢 Low	4

Panel: 6/6 reviewers contributed findings.

[christian-byrne]

Three contract gaps found.

Full context for agent readers

Gates: uv run --locked --extra dev ruff check . passed (All checks passed!); ruff format --check . passed (449 files already formatted); focused tests passed (17 passed in 0.13s). Full pytest completed with 7413 passed, 32 skipped, 46 failed; failures are pre-existing/environmental run/preflight cache, digest-cache timing, rendering, and umask failures, with none in changed-area tests.

Reviewer probes: edit ops carrying definitions were rejected; exact replay of a serialized op was byte-stable and idempotent; field names/casing match the cloud relay pull request (subgraph_id, subgraph_definition); help describes creation only. Three uniqueness probes failed (ancestor/descendant, cross-branch, and collision with an existing nested definition), and malformed nested replay was accepted. Temporary probe file was deleted and the checkout was clean before submission.

Could not verify the full suite as green because of the 46 unrelated failures above.

[christian-byrne]

Ownership boundary is still inverted.
CLI mutates locally instead of sending.
Contract docs contradict replay behavior.

Full context for agent readers

Reviewed the full five-file diff and surrounding workflow edit, batch, replay, conflict, and serialization paths. Rechecked all 12 resolved threads: their narrow fixes are present, but the resulting implementation still assigns cmp-owned validation/apply/replay to Python.

Verification:

• uv sync --all-extras: succeeded, 72 packages installed.
• uv run pytest -q tests/comfy_cli/test_define_subgraph_op.py tests/comfy_cli/test_op_vocabulary_contract.py: 33 passed.
• uv run ruff check .: passed.
• uv run ruff format --check comfy_cli/command/workflow.py comfy_cli/command/workflow_edit.py comfy_cli/workflow_ops.py tests/comfy_cli/test_define_subgraph_op.py: 4 files already formatted.
• uv run pytest -q: 7,430 passed, 32 skipped, 45 failed; failures are existing cached object-info/run preflight and umask expectations, not changed-area collection failures.

Glossary: cmp = @comfyorg/comfy-multi-player, the owner of define/validate/apply/replay/project behavior; CRDT = conflict-free replicated data type.