feat(cli): bulk writers emit op batches + guarded reset_doc

[skishore23]

Linear: BE-7171 (V1-038) — the comfy-cli half. Cloud half: Comfy-Org/cloud (linked below once open).

Why

comfy templates fetch -o <file> is a bulk writer: it replaces the working file wholesale. Downstream — in the cloud agent's shared document — that replacement could only be expressed one way: re-mint the whole document from the new file. That is the gap this closes.

Re-minting is bad for two reasons:

1. It throws away the attributed, incremental op history the document exists to keep. A template fetch appears as "the document is now something else", with no author, no ops, nothing to replay.
2. op-vocabulary-v1 §8.6 is explicit that independently re-seeding a base is the one thing a replica must never do — the duplicate identities are invisible until the first merge.

What

templates fetch --emit-ops

Emits data.ops: the stamped op batch that turns the file being replaced INTO the template.

delete_node × (nodes currently in the target file)
add_node    × (template nodes)
connect     × (template links)

No set_widget ops — widget values ride inside the add_node payload, which §8.5 makes authoritative at replay. New flags: --emit-ops, --actor, --base-version.

Two contracts, both tested.

	consumer	guarantee
op contract	apply_op replay (what the cloud forwards to the doc host)	reproduces the template exactly — classes, wiring, positions, widget values
spec contract	apply_specs (comfy workflow apply --ops)	accepts the array verbatim, rebuilds the structure — the same bar nodes path --emit-ops already meets

Each entry is dual-shape to satisfy both: a fully minted op (envelope + minted fields) that also carries that kind's spec keys (class_type/at/as, from/to, node). The two are not equivalent and the docstring says so: apply_specs re-mints each node from the live catalog, so it reproduces structure; the op path reproduces the graph.

Identity is re-minted, never inherited. Template graphs are numbered from small frontend counters (1, 2, 3…). Replaying those ids into a live document reuses identities a concurrent replica may still hold — §1.5's "a merge could resurrect a deleted node" hazard. Every node and link gets a fresh mint_id; every interior reference (inputs[].link, outputs[].links, the links tuples) is remapped onto it.

All or nothing. A graph the frozen vocabulary cannot express — a subgraph definition, a canvas group, a reroute point, a malformed node/link — emits no ops at all and reports ops_skipped: "<reason>". A partial batch is the dangerous answer: it applies cleanly and leaves a document that is not the graph the caller asked for. The consumer keeps its whole-document fallback for exactly these.

Without the flag the envelope is byte-identical to before (asserted).

reset_doc — un-deferred and guarded

reset_doc was frozen in §1.6 but left deferred (apply_op rejected it; DEFERRED_OPS pinned that). It is now implemented:

• comfy workflow reset-doc <file> --confirm. Without --confirm the command fails closed with workflow_reset_doc_unconfirmed and writes nothing. The check runs before the file is read, so an unconfirmed call cannot fail halfway. It is the only guarded edit command — because it is the only one no later op can undo.
• A history barrier, not a clear. clear empties the graph but preserves the id high-water marks and _applied_ops, so it merges like any other edit. reset_doc drops those too, plus _widget_stamps; only the document id survives. Safe because ids come from mint_id, never from the high-water marks (§8.3).
• Idempotent. The reset's own op_id is written into the freshly-emptied _applied_ops, so a re-delivered reset_doc is a no-op rather than a second wipe. (apply_op now re-reads workflow["_applied_ops"] instead of appending to the pre-dispatch binding — that binding is stale precisely for this kind.)
• Standalone-only, with its own registered code workflow_reset_doc_not_batchable. NotBatchableError is now per-kind; the class attributes keep the clear values so existing callers reading them off the class still resolve.
• Never emitted implicitly — no --emit-ops surface and no bulk writer mints one. Replacing a canvas is deletes+adds, which merge; a barrier does not.

DEFERRED_OPS is now empty.

Doc

Per §9's amendment rule, docs/op-vocabulary-v1.md gains amendment v1.1 (§10) and a new normative §8.8 (bulk writers emit ops, they do not re-seed). §1.6 is rewritten from "semantics when implemented" to the implemented contract. No frozen kind was added, removed, or re-scoped — reset_doc was already in FROZEN_OPS and already Batchable = no.

Test evidence

Red first, then green. New files:

• tests/comfy_cli/command/test_templates_fetch_emit_ops.py — test_template_fetch_emits_op_batch (stamping, ordering, exact op-replay round-trip, minted-id assertion, the written file is unchanged), test_emitted_batch_round_trips_through_apply_specs, test_without_the_flag_the_envelope_is_unchanged, test_emit_ops_on_a_fresh_canvas_has_no_deletes, test_inexpressible_template_emits_no_ops_and_says_why, test_emit_ops_without_out_still_emits.
• tests/comfy_cli/test_reset_doc_op.py — test_reset_doc_requires_confirm (envelope code + the file is byte-for-byte untouched), test_reset_doc_with_confirm_empties_the_document, test_reset_doc_rejected_in_batch, test_reset_doc_rejected_through_the_apply_command, test_apply_op_replays_reset_doc_and_records_it, test_reset_doc_is_no_longer_deferred.

$ uv run pytest tests/comfy_cli/test_reset_doc_op.py \
    tests/comfy_cli/command/test_templates_fetch_emit_ops.py
11 failed, 1 passed          # before implementation

$ uv run pytest tests/comfy_cli -k "workflow or template or op_vocab or reset_doc or error_code"
770 passed, 2 skipped, 3830 deselected

The doc↔code contract test tests/comfy_cli/test_op_vocabulary_contract.py is green unchanged — it discovers apply_op / apply_specs dispatch behaviorally, so un-deferring reset_doc had to move the doc table, the constants and both dispatch tables together or it would have failed.

ruff check / ruff format --check clean on every touched file (the 17 repo-wide ruff check findings are pre-existing in untouched files). Full suite: 31 failures, of which 29 reproduce on the base branch with this diff stashed (test_logs.py, test_jobs.py, test_host_port.py, test_onboarding.py, test_run_json.py — environment-dependent) and the remaining 2 were introduced-and-fixed here (test_every_registered_code_is_raised needed the new code to be discoverable by the AST scanner — _NOT_BATCHABLE values are dicts with a "code" key for that reason).

Base caveat

Targets kishore/v1-p2-integration, not master — it builds on the frozen-vocabulary work that lands there. Rebase onto master once the P2 integration branch merges; nothing here depends on P2 beyond the vocabulary doc and FROZEN_OPS/DEFERRED_OPS constants.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7e4cb2bc-0845-49c4-ac1c-9bb2acbabb32

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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