From f88c1909579d3ead6afb5fc71faad2d40d4a5132 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 21 Sep 2026 01:25:30 -0700 Subject: [PATCH 01/30] fix(workflow): reject reused op ids with changed payloads --- comfy_cli/workflow_ops.py | 47 +++++++++++++++++++- docs/op-vocabulary-v1.md | 7 ++- tests/comfy_cli/test_op_id_reuse_contract.py | 45 +++++++++++++++++++ 3 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 tests/comfy_cli/test_op_id_reuse_contract.py diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 34bb0dd2e..ed634b46e 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -52,6 +52,7 @@ from __future__ import annotations import copy +import hashlib import json import math import random @@ -73,6 +74,43 @@ # frontend counter ids), always inside JS Number.MAX_SAFE_INTEGER. _ID_FLOOR = 1 << 40 +_MAX_OP_PAYLOAD_DEPTH = 64 +_MAX_OP_COLLECTION_ENTRIES = 4096 +_MAX_OP_COST = 262_144 + + +def _canonical_op(op: dict) -> str: + cost = 0 + stack: list[tuple[Any, int]] = [(op, 0)] + while stack: + value, depth = stack.pop() + if depth > _MAX_OP_PAYLOAD_DEPTH: + raise ValueError(f"payload_too_deep: op payload nests deeper than {_MAX_OP_PAYLOAD_DEPTH} levels") + cost += 1 + if isinstance(value, str): + cost += len(value) + elif isinstance(value, dict): + if len(value) > _MAX_OP_COLLECTION_ENTRIES: + raise ValueError(f"malformed_op: object exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") + cost += 4 + sum(len(str(key)) for key in value) + stack.extend((child, depth + 1) for child in value.values()) + elif isinstance(value, list | tuple): + if len(value) > _MAX_OP_COLLECTION_ENTRIES: + raise ValueError(f"malformed_op: array exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") + cost += 4 + stack.extend((child, depth + 1) for child in value) + else: + cost += 8 + if cost > _MAX_OP_COST: + raise ValueError(f"malformed_op: payload exceeds the {_MAX_OP_COST}-unit cost budget") + try: + return json.dumps(op, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False) + except (TypeError, ValueError) as exc: + raise ValueError(f"malformed_op: op payload is not canonical JSON: {exc}") from exc + +def _op_digest(op: dict) -> str: + return hashlib.sha256(_canonical_op(op).encode("utf-8")).hexdigest() + def mint_id() -> int: """A leaderless, collision-free, int-typed identity for a node or link.""" @@ -2996,10 +3034,14 @@ def apply_specs( def apply_op(workflow: dict, op: dict, graph) -> dict: """Replay one op onto ``workflow`` in place and return it. Idempotent: an - op whose ``op_id`` was already applied is a no-op.""" + op whose ``op_id`` was already applied is a no-op only for one payload.""" had_applied_ops = "_applied_ops" in workflow + digest = _op_digest(op) applied = workflow.setdefault("_applied_ops", []) if op["op_id"] in applied: + recorded = (workflow.get("_applied_op_digests") or {}).get(op["op_id"]) + if recorded is not None and recorded != digest: + raise ValueError(f"op_id_reuse: op_id {op['op_id']!r} was already applied with a different payload") return workflow kind = op["op"] if kind != "insert_workflow" and "definitions" in op: @@ -3059,6 +3101,7 @@ def apply_op(workflow: dict, op: dict, graph) -> dict: # written into a discarded list. Re-read, so a re-delivered reset_doc is a # no-op rather than a second wipe. workflow.setdefault("_applied_ops", []).append(op["op_id"]) + workflow.setdefault("_applied_op_digests", {})[op["op_id"]] = digest deferred = workflow.get("_deferred_widget_ops") if isinstance(deferred, dict): deferred.pop(op["op_id"], None) @@ -3784,6 +3827,7 @@ def _apply_reset_doc(workflow: dict, op: dict) -> None: workflow["last_node_id"] = 0 workflow["last_link_id"] = 0 workflow["_applied_ops"] = [] + workflow["_applied_op_digests"] = {} workflow["_widget_stamps"] = {} @@ -4006,6 +4050,7 @@ def strip_internal(workflow: dict) -> dict: file writes, ``--stdout`` and batch output alike. """ workflow.pop("_applied_ops", None) + workflow.pop("_applied_op_digests", None) workflow.pop("_widget_stamps", None) workflow.pop("_pending_dynamic_connects", None) workflow.pop("_deferred_widget_ops", None) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index cad1cbaaf..ff9364633 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -338,13 +338,16 @@ local model can need it. * Every op carries `op_id`: uuid4 hex, minted by the **creator, before dispatch** (`_new_op`). Receivers never regenerate or rewrite an `op_id`. -* `apply_op` records applied `op_id`s in the document's `_applied_ops` list and - drops any op whose `op_id` is already there. **Uniqueness scope is +* `apply_op` records applied `op_id`s in `_applied_ops` and records `sha256(canonical_op)` in `_applied_op_digests`. An identical retry is a no-op; reuse with a different canonical payload rejects with `op_id_reuse`. Legacy documents with only the list retain their historical duplicate behavior. **Uniqueness scope is PER-WORKFLOW**: the same `op_id` can exist in two different workflow documents without interaction; within one document each op applies exactly once. * `_applied_ops` (and `_widget_stamps`) are apply-time bookkeeping, stripped before serialization to disk (`strip_internal`). +## Amendment v1.6 — canonical op identity + +`op_id` identifies one immutable semantic-op envelope. The canonical form is compact UTF-8 JSON over the whole envelope, with object keys sorted by Unicode code point at every depth and array order preserved. The replay ledger records its lowercase SHA-256 digest. Reusing an `op_id` with a different canonical payload rejects before mutation with `op_id_reuse`; an identical retry remains a no-op. Canonicalization is bounded to 64 levels, 4,096 entries per collection, and 262,144 approximate cost units. This mirrors comfy-multi-player schema Amendment A8. The asymmetric case is load-bearing: `{value: 25}` followed by the same `op_id` carrying `{value: 30}` rejects, while key insertion order is immaterial. + ## 3. Conflict rules Scalar conflicts resolve by last-writer-wins on the op stamp. The stamp is diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py new file mode 100644 index 000000000..1b6c30110 --- /dev/null +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -0,0 +1,45 @@ +import copy + +import pytest + +from comfy_cli import workflow_ops as ops + + +class _Graph: + def widget_order_for_node(self, _class_type, _values): + return ["steps"] + + +def _workflow(): + return {"nodes": [{"id": 7, "type": "KSampler", "widgets_values": [20], "inputs": [], "outputs": []}], "links": []} + + +def _op(value=25): + return { + "op": "set_widget", + "op_id": "same0000000000000000000000000000", + "actor": "human:a", + "base_version": 5, + "stamp": [5, "human:a"], + "node_id": 7, + "widget": "steps", + "value": value, + } + + +def test_changed_payload_reusing_op_id_rejects_without_mutation(): + workflow = _workflow() + ops.apply_op(workflow, _op(25), _Graph()) + before = copy.deepcopy(workflow) + with pytest.raises(ValueError, match="^op_id_reuse:"): + ops.apply_op(workflow, _op(30), _Graph()) + assert workflow == before + + +def test_canonical_digest_matches_cmp_a8_vector_and_key_order_is_immaterial(): + workflow = _workflow() + first = _op() + ops.apply_op(workflow, first, _Graph()) + assert workflow["_applied_op_digests"][first["op_id"]] == "d395ba92dd991c07c0f790b974b3d4f34e3b29c71a26621634d75de31040a431" + reordered = dict(reversed(list(first.items()))) + assert ops.apply_op(workflow, reordered, _Graph()) is workflow From 7682389130f7b6fd7c245879de6c9a9b7b8fd6b2 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 21 Sep 2026 01:27:12 -0700 Subject: [PATCH 02/30] style: apply remote ruff formatting --- comfy_cli/workflow_ops.py | 1 + tests/comfy_cli/test_op_id_reuse_contract.py | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index ed634b46e..771271d8c 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -108,6 +108,7 @@ def _canonical_op(op: dict) -> str: except (TypeError, ValueError) as exc: raise ValueError(f"malformed_op: op payload is not canonical JSON: {exc}") from exc + def _op_digest(op: dict) -> str: return hashlib.sha256(_canonical_op(op).encode("utf-8")).hexdigest() diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 1b6c30110..0eb429a86 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -40,6 +40,9 @@ def test_canonical_digest_matches_cmp_a8_vector_and_key_order_is_immaterial(): workflow = _workflow() first = _op() ops.apply_op(workflow, first, _Graph()) - assert workflow["_applied_op_digests"][first["op_id"]] == "d395ba92dd991c07c0f790b974b3d4f34e3b29c71a26621634d75de31040a431" + assert ( + workflow["_applied_op_digests"][first["op_id"]] + == "d395ba92dd991c07c0f790b974b3d4f34e3b29c71a26621634d75de31040a431" + ) reordered = dict(reversed(list(first.items()))) assert ops.apply_op(workflow, reordered, _Graph()) is workflow From 2d22c0ee63b5e8e6c0b58ce1c4d29542f285d22d Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 21 Sep 2026 01:39:29 -0700 Subject: [PATCH 03/30] fix: preserve replay metadata boundaries --- comfy_cli/workflow_ops.py | 7 +++++-- tests/comfy_cli/test_op_id_reuse_contract.py | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 771271d8c..028d63249 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3037,13 +3037,15 @@ def apply_op(workflow: dict, op: dict, graph) -> dict: """Replay one op onto ``workflow`` in place and return it. Idempotent: an op whose ``op_id`` was already applied is a no-op only for one payload.""" had_applied_ops = "_applied_ops" in workflow - digest = _op_digest(op) applied = workflow.setdefault("_applied_ops", []) if op["op_id"] in applied: recorded = (workflow.get("_applied_op_digests") or {}).get(op["op_id"]) - if recorded is not None and recorded != digest: + if recorded is None: + return workflow + if recorded != _op_digest(op): raise ValueError(f"op_id_reuse: op_id {op['op_id']!r} was already applied with a different payload") return workflow + digest = _op_digest(op) kind = op["op"] if kind != "insert_workflow" and "definitions" in op: raise ValueError(f"malformed_op: {kind} does not accept definitions") @@ -3944,6 +3946,7 @@ def canonical(workflow: dict) -> dict: """ w = copy.deepcopy(workflow) w.pop("_applied_ops", None) + w.pop("_applied_op_digests", None) w.pop("_widget_stamps", None) w.pop("_pending_dynamic_connects", None) w.pop("_deferred_widget_ops", None) diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 0eb429a86..3c8367b22 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -46,3 +46,19 @@ def test_canonical_digest_matches_cmp_a8_vector_and_key_order_is_immaterial(): ) reordered = dict(reversed(list(first.items()))) assert ops.apply_op(workflow, reordered, _Graph()) is workflow + + +def test_legacy_list_only_replay_returns_before_digesting_payload(): + workflow = _workflow() + workflow["_applied_ops"] = [_op()["op_id"]] + replay = _op() + replay["value"] = object() + assert ops.apply_op(workflow, replay, _Graph()) is workflow + + +def test_canonical_ignores_replay_digest_metadata(): + workflow = _workflow() + applied = copy.deepcopy(workflow) + ops.apply_op(applied, _op(), _Graph()) + applied["nodes"] = copy.deepcopy(workflow["nodes"]) + assert ops.canonical(applied) == ops.canonical(workflow) From e056a7a9ef2fb859f6f5527312cc15d706f08af2 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 21 Sep 2026 01:45:35 -0700 Subject: [PATCH 04/30] fix: bind enriched widget ops to final payload --- comfy_cli/workflow_ops.py | 2 ++ tests/comfy_cli/command/test_workflow_edit_promoted.py | 2 ++ 2 files changed, 4 insertions(+) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 028d63249..995f02c4d 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -1157,6 +1157,7 @@ def _set_widget_impl( # resolution is the pre-fork sibling, not the written one. written = _engine._resolve_node_path(workflow, list(target.segments), _engine._subgraph_defs_by_id(workflow)) op["promoted"]["host_widgets_values"] = _promoted.host_widgets_values(written) + workflow["_applied_op_digests"][op["op_id"]] = _op_digest(op) return workflow, op if target.kind == "legacy_primitive": # A frontend-only PrimitiveNode has no catalog entry, so every @@ -1179,6 +1180,7 @@ def _set_widget_impl( ) workflow = apply_op(workflow, op, graph) op["promoted"]["host_widgets_values"] = list(src.get("widgets_values") or []) + workflow["_applied_op_digests"][op["op_id"]] = _op_digest(op) return workflow, op if target.kind == "top" and target.redirected_from is not None: node_id = target.node.get("id") diff --git a/tests/comfy_cli/command/test_workflow_edit_promoted.py b/tests/comfy_cli/command/test_workflow_edit_promoted.py index 21f36a21b..75eb3b97d 100644 --- a/tests/comfy_cli/command/test_workflow_edit_promoted.py +++ b/tests/comfy_cli/command/test_workflow_edit_promoted.py @@ -95,6 +95,7 @@ def test_promoted_address_writes_the_host_value(graph): assert "path" not in op assert op["promoted"]["value_index"] == 1 assert op["promoted"]["host_widgets_values"] == expected + assert workflow_ops.apply_op(wf, op, graph) is wf def test_interior_address_of_a_promoted_widget_is_redirected_to_the_host(graph): @@ -442,6 +443,7 @@ def test_legacy_primitive_write_carries_a_positional_payload(graph): assert op["promoted"] == {"value_index": 0, "instance_path": [str(legacy)], "host_widgets_values": [512, "fixed"]} replayed = workflow_ops.apply_op(copy.deepcopy(base), op, graph) assert _node(replayed, legacy)["widgets_values"] == [512, "fixed"] + assert workflow_ops.apply_op(wf, op, graph) is wf def test_later_connect_to_a_materialized_promoted_input_stays_on_the_declared_register(graph): From 4c537fd298c3b1ad61168064fb8cead265b8ab28 Mon Sep 17 00:00:00 2001 From: bymyself Date: Fri, 23 Oct 2026 06:14:54 +0000 Subject: [PATCH 05/30] fix(workflow): carry the op-id/payload binding onto current main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebase of this branch onto main, where `workflow_ops.apply_op` has since grown the deferred hidden-widget queue (`_deferred_widget_ops`) and the `_applied_ops` leak guard. Three follow-on repairs: * `_retry_deferred_widget_ops` appends to `_applied_ops` directly, so a deferred write never passed through `apply_op`'s tail and got no digest. The reuse gate would then read it as a legacy list-only entry and silently no-op a changed-payload retry of that id. Record the canonical digest there too, and pin it. * `tests/comfy_cli/test_op_id_reuse_contract.py` drove `apply_op` with a hand-rolled `_Graph` stub that answered only `widget_order_for_node`. The real `set_widget` write path reads the node's schema through `graph.node`, so the three behavioural cases never reached the write at all (`AttributeError: '_Graph' object has no attribute 'node'`) — this was never upstream drift; the stub was insufficient from the start. Build a real `Graph` from a one-node `object_info` instead. Assertions are unchanged: the A8 vector, the reject-without-mutation case, and the canonical-ignores-digest case all still hold. * Two test-local strippers popped `_applied_ops` and `_widget_stamps` but not the new `_applied_op_digests`, so a "both write paths agree modulo apply-time bookkeeping" comparison diffed on the bookkeeping itself (`test_set_slot_path_repairs_like_set_widget`). Teach them the key. --- comfy_cli/workflow_ops.py | 5 ++ tests/comfy_cli/command/test_workflow_edit.py | 1 + .../test_workflow_edit_legacy_proxy.py | 1 + .../test_dynamic_combo_other_option_widget.py | 33 ++++++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 51 ++++++++++++++----- 5 files changed, 78 insertions(+), 13 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 995f02c4d..eb3352b42 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3134,6 +3134,11 @@ def _retry_deferred_widget_ops(workflow: dict, graph) -> None: if _apply_set_widget(workflow, op, graph) is False: continue workflow.setdefault("_applied_ops", []).append(op_id) + # Bind the id to its canonical payload here too: a deferred write + # reaches ``_applied_ops`` through this loop and never through + # ``apply_op``'s tail, so without this the reuse gate would read it + # as a legacy list-only entry and silently no-op a changed retry. + workflow.setdefault("_applied_op_digests", {})[op_id] = _op_digest(op) pending.pop(op_id, None) progressed = True if not progressed: diff --git a/tests/comfy_cli/command/test_workflow_edit.py b/tests/comfy_cli/command/test_workflow_edit.py index 2ebe148f0..4d03c0441 100644 --- a/tests/comfy_cli/command/test_workflow_edit.py +++ b/tests/comfy_cli/command/test_workflow_edit.py @@ -977,6 +977,7 @@ def test_repair_replays_identically_on_a_fresh_copy(self): replayed = workflow_ops.apply_op(copy.deepcopy(base), op, _graph()) for w in (applied, replayed): w.pop("_applied_ops", None) + w.pop("_applied_op_digests", None) w.pop("_widget_stamps", None) assert json.dumps(replayed, sort_keys=True) == json.dumps(applied, sort_keys=True) diff --git a/tests/comfy_cli/command/test_workflow_edit_legacy_proxy.py b/tests/comfy_cli/command/test_workflow_edit_legacy_proxy.py index beab7ef45..168269187 100644 --- a/tests/comfy_cli/command/test_workflow_edit_legacy_proxy.py +++ b/tests/comfy_cli/command/test_workflow_edit_legacy_proxy.py @@ -69,6 +69,7 @@ def _interior(wf: dict, instance_id: Any, inner_id: Any) -> dict: def _stripped(wf: dict) -> str: w = copy.deepcopy(wf) w.pop("_applied_ops", None) + w.pop("_applied_op_digests", None) w.pop("_widget_stamps", None) return json.dumps(w, sort_keys=True) diff --git a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py index fcedd81da..8d8ad3781 100644 --- a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py +++ b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py @@ -565,3 +565,36 @@ def test_missing_nested_selector_uses_the_active_outer_options_default(): assert "model.mode='quick'" in msg, msg assert "'detailed'" in msg, msg assert wf["nodes"][0]["widgets_values"] == before + + +def test_a_deferred_write_is_bound_to_its_canonical_payload_once_applied(graph): + """A deferred write reaches ``_applied_ops`` through the retry loop, not + through ``apply_op``'s tail, so the op-id/payload binding (op-vocabulary + Amendment v1.6) has to be recorded there too. Without it the reuse gate + sees a list-only entry and silently no-ops a changed-payload retry.""" + wf, node_id = _fresh(graph) + hidden_write = workflow_ops._new_op( + "set_widget", + "agent-a", + 1, + node_id=node_id, + widget="model.prompt_expansion_mode", + value="quality", + ) + workflow_ops.apply_op(wf, hidden_write, graph) + assert hidden_write["op_id"] in wf["_deferred_widget_ops"] + + wf, _ = workflow_ops.set_widget(wf, graph, node_id, "model", "MiniMax H3 Max", actor="agent-b") + + assert hidden_write["op_id"] in wf["_applied_ops"] + assert wf["_applied_op_digests"][hidden_write["op_id"]] == workflow_ops._op_digest(hidden_write) + + # An identical redelivery stays a no-op; the same id with a changed payload + # is refused rather than dropped. + assert workflow_ops.apply_op(wf, copy.deepcopy(hidden_write), graph) is wf + changed = copy.deepcopy(hidden_write) + changed["value"] = "balanced" + before = copy.deepcopy(wf) + with pytest.raises(ValueError, match="^op_id_reuse:"): + workflow_ops.apply_op(wf, changed, graph) + assert wf == before diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 3c8367b22..4eee1c30d 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -1,13 +1,38 @@ +"""``op_id`` is bound to one canonical payload (op-vocabulary Amendment v1.6 / CMP A8). + +The graph here is a real :class:`~comfy_cli.cql.engine.Graph` built from a +one-node ``object_info``, not a hand-rolled stub. ``apply_op`` -> ``set_widget`` +goes through the catalog (``graph.node`` for the schema, ``widget_order_for_node`` +for the positional slot), so a stub that answers only the widget order cannot +reach the write at all. +""" + +from __future__ import annotations + import copy +from typing import Any import pytest from comfy_cli import workflow_ops as ops +from comfy_cli.cql.engine import Graph + +_OBJECT_INFO: dict[str, Any] = { + "KSampler": { + "input": {"required": {"steps": ["INT", {"default": 20, "min": 1, "max": 10000}]}}, + "input_order": {"required": ["steps"]}, + "output": ["LATENT"], + "output_name": ["LATENT"], + "category": "sampling", + "display_name": "KSampler", + "python_module": "nodes", + }, +} -class _Graph: - def widget_order_for_node(self, _class_type, _values): - return ["steps"] +@pytest.fixture +def graph() -> Graph: + return Graph.from_object_info(_OBJECT_INFO) def _workflow(): @@ -27,38 +52,38 @@ def _op(value=25): } -def test_changed_payload_reusing_op_id_rejects_without_mutation(): +def test_changed_payload_reusing_op_id_rejects_without_mutation(graph): workflow = _workflow() - ops.apply_op(workflow, _op(25), _Graph()) + ops.apply_op(workflow, _op(25), graph) before = copy.deepcopy(workflow) with pytest.raises(ValueError, match="^op_id_reuse:"): - ops.apply_op(workflow, _op(30), _Graph()) + ops.apply_op(workflow, _op(30), graph) assert workflow == before -def test_canonical_digest_matches_cmp_a8_vector_and_key_order_is_immaterial(): +def test_canonical_digest_matches_cmp_a8_vector_and_key_order_is_immaterial(graph): workflow = _workflow() first = _op() - ops.apply_op(workflow, first, _Graph()) + ops.apply_op(workflow, first, graph) assert ( workflow["_applied_op_digests"][first["op_id"]] == "d395ba92dd991c07c0f790b974b3d4f34e3b29c71a26621634d75de31040a431" ) reordered = dict(reversed(list(first.items()))) - assert ops.apply_op(workflow, reordered, _Graph()) is workflow + assert ops.apply_op(workflow, reordered, graph) is workflow -def test_legacy_list_only_replay_returns_before_digesting_payload(): +def test_legacy_list_only_replay_returns_before_digesting_payload(graph): workflow = _workflow() workflow["_applied_ops"] = [_op()["op_id"]] replay = _op() replay["value"] = object() - assert ops.apply_op(workflow, replay, _Graph()) is workflow + assert ops.apply_op(workflow, replay, graph) is workflow -def test_canonical_ignores_replay_digest_metadata(): +def test_canonical_ignores_replay_digest_metadata(graph): workflow = _workflow() applied = copy.deepcopy(workflow) - ops.apply_op(applied, _op(), _Graph()) + ops.apply_op(applied, _op(), graph) applied["nodes"] = copy.deepcopy(workflow["nodes"]) assert ops.canonical(applied) == ops.canonical(workflow) From b313d3d5a87c4d713a1b7c44db4ed16e9aa2e82a Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 24 Oct 2026 02:15:03 +0000 Subject: [PATCH 06/30] fix(workflow): canonicalize op payloads the way ECMAScript does MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The canonical form has to be byte-identical on both sides of the wire — the comfy-multi-player A8 counterpart builds it with `JSON.stringify` — and `json.dumps` disagreed with that on exactly the shapes a FLOAT widget produces: an integral float (`20.0` vs `20`), negative zero (`-0.0` vs `0`) and an exponent (`1e-07` vs `1e-7`). A FLOAT `set_widget` relayed through JS therefore digested differently on the two sides, so an identical redelivery was rejected as `op_id_reuse` and no float payload ever matched cross-implementation. The A8 test vector is all integers, so nothing caught it. Replaces the walk-then-`json.dumps` pair with one recursive writer that renders numbers per ECMA-262 `Number::toString`, verified against Node's `JSON.stringify` over 9,997 float bit patterns (subnormals, 1e21 boundary, shortest-repr cases) and 600 random nested structures. The pinned A8 digest `d395ba92…` is unchanged. Two further canonicalization defects, same path: * non-finite numbers now render as `null`, which is what `JSON.stringify` does. Rejecting them (`allow_nan=False`) made a widget whose *current* value is NaN/Infinity impossible to overwrite, because the op captures that value in `old` and `json.load` accepts both spellings on the way in. * a lone surrogate is escaped as `\udXXX`, matching ES2019 well-formed stringify. Emitted raw it cannot be UTF-8 encoded at all, so the encode — which sat outside the try/except — died with a bare `UnicodeEncodeError` instead of a `malformed_op:`-prefixed `ValueError`, and callers that classify errors by prefix got it wrong. The bounds are raised from 4,096 entries / 262,144 cost units to 1,048,576 / 33,554,432. The digest is computed on every apply rather than only on a reuse comparison, so the old pair rejected edits that used to succeed: `clear` and `reset_doc` enumerate every node id in `removed_nodes`, a `delete_node` on a hub node enumerates every incident link, and a prompt value (or the `old` value an op captures) runs past 256K characters routinely. They still exist to stop a runaway payload pinning a replica inside canonicalization. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538098 https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538100 https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538105 --- comfy_cli/workflow_ops.py | 178 ++++++++++++++++--- tests/comfy_cli/test_op_id_reuse_contract.py | 91 +++++++++- 2 files changed, 239 insertions(+), 30 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index eb3352b42..769e519fc 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -58,6 +58,7 @@ import random import re import uuid +from decimal import Decimal from typing import Any from comfy_cli import layout @@ -75,38 +76,157 @@ _ID_FLOOR = 1 << 40 _MAX_OP_PAYLOAD_DEPTH = 64 -_MAX_OP_COLLECTION_ENTRIES = 4096 -_MAX_OP_COST = 262_144 +# Bounded only so a hostile or runaway payload cannot pin a replica inside +# canonicalization. Every ORDINARY op has to pass, because the digest is now +# computed on every apply rather than only on a reuse comparison, and the first +# bounds (4,096 entries / 262,144 cost units) were tight enough to reject real +# edits: `clear` / `reset_doc` enumerate every node id in `removed_nodes`, a +# `delete_node` on a hub node enumerates every incident link, and a prompt +# widget value (or the `old` value an op captures) routinely runs past 256K +# characters. +_MAX_OP_COLLECTION_ENTRIES = 1_048_576 +_MAX_OP_COST = 33_554_432 + +#: Any surrogate code point in a Python ``str`` is a LONE surrogate — astral +#: characters are single code points there — so matching the whole block is +#: enough to find the ones that cannot be UTF-8 encoded. +_LONE_SURROGATE = re.compile("[\ud800-\udfff]") + + +def _es_number(value: float) -> str: + """Render a float exactly as ECMAScript ``Number::toString`` does. + + The canonical form has to be byte-identical on both sides of the wire, and + the counterpart implementation (comfy-multi-player schema Amendment A8) + builds it with ``JSON.stringify``. Python's own float repr disagrees with + that on three shapes a FLOAT widget produces constantly — an integral float + (``20.0`` vs ``20``), negative zero (``-0.0`` vs ``0``) and an exponent + (``1e-07`` vs ``1e-7``) — so digesting Python's spelling would reject an + identical op that had merely been relayed through JS as ``op_id_reuse``, and + no float payload would ever digest the same on the two sides. + + ``repr`` is still the input: it is the shortest round-tripping decimal, the + same digit string ECMAScript's algorithm starts from. Only the rendering of + that digit string differs, and this reimplements it (ECMA-262 + ``Number::toString``, the ``k``/``n``/``s`` case analysis). + """ + if value == 0: # also folds -0.0, which ECMAScript renders as "0" + return "0" + if value < 0: + return "-" + _es_number(-value) + _, raw_digits, exponent = Decimal(repr(value)).as_tuple() + digits = list(raw_digits) + # ECMAScript picks the `s` that is NOT divisible by 10, so trailing zeros + # move into the exponent instead of into the digit string. + while len(digits) > 1 and digits[-1] == 0: + digits.pop() + exponent += 1 + s = "".join(str(d) for d in digits) + k = len(s) + n = exponent + k + if k <= n <= 21: + return s + "0" * (n - k) + if 0 < n <= 21: + return f"{s[:n]}.{s[n:]}" + if -6 < n <= 0: + return "0." + "0" * -n + s + e = n - 1 + mantissa = s if k == 1 else f"{s[0]}.{s[1:]}" + return f"{mantissa}e{'+' if e >= 0 else '-'}{abs(e)}" + + +def _canonical_string(value: str) -> str: + """One JSON string literal, escaped the way ``JSON.stringify`` escapes it. + + ``json.dumps`` already escapes exactly the code points ``JSON.stringify`` + does, so the two agree on every well-formed string. They disagree on a lone + surrogate — which ``json.loads('"\\ud800"')`` happily produces: ES2019 + well-formed stringify emits it as a ``\\udXXX`` escape, Python emits it raw. + A raw surrogate cannot be UTF-8 encoded at all, so leaving it would make the + digest die with a bare ``UnicodeEncodeError`` outside the ``malformed_op:`` + contract callers classify errors by. Escaping it both matches ECMAScript and + keeps the encode in :func:`_op_digest` total. + """ + literal = json.dumps(value, ensure_ascii=False) + if _LONE_SURROGATE.search(literal): + literal = _LONE_SURROGATE.sub(lambda m: f"\\u{ord(m.group()):04x}", literal) + return literal + + +def _canonical_key(key: Any) -> str: + """An object key as its string form, matching ECMAScript property coercion.""" + if isinstance(key, str): + return key + if isinstance(key, bool): # before int: bool is an int subclass + return "true" if key else "false" + if isinstance(key, int): + return str(key) + if isinstance(key, float): + if math.isnan(key): + return "NaN" + if math.isinf(key): + return "Infinity" if key > 0 else "-Infinity" + return _es_number(key) + if key is None: + return "null" + raise ValueError(f"malformed_op: object key of type {type(key).__name__} is not canonical JSON") + + +def _canonical_value(value: Any, depth: int, budget: list[int]) -> str: + if depth > _MAX_OP_PAYLOAD_DEPTH: + raise ValueError(f"payload_too_deep: op payload nests deeper than {_MAX_OP_PAYLOAD_DEPTH} levels") + budget[0] += 1 + if value is None: + budget[0] += 8 + rendered = "null" + elif isinstance(value, bool): # before int: bool is an int subclass + budget[0] += 8 + rendered = "true" if value else "false" + elif isinstance(value, int): + budget[0] += 8 + rendered = str(value) + elif isinstance(value, float): + budget[0] += 8 + # ``JSON.stringify`` renders every non-finite number as ``null``, so + # doing the same is what makes the two canonical forms agree. It also + # un-breaks overwriting a widget whose CURRENT value is NaN/Infinity + # (Python's ``json.load`` accepts both, and the op captures it in + # ``old``), which the previous ``allow_nan=False`` rejected outright. + rendered = _es_number(value) if math.isfinite(value) else "null" + elif isinstance(value, str): + budget[0] += len(value) + rendered = _canonical_string(value) + elif isinstance(value, dict): + if len(value) > _MAX_OP_COLLECTION_ENTRIES: + raise ValueError(f"malformed_op: object exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") + budget[0] += 4 + members = [] + for key in value: + name = _canonical_key(key) + budget[0] += len(name) + members.append((name, value[key])) + # Unicode code point order at every depth: Python sorts `str` that way. + members.sort(key=lambda member: member[0]) + rendered = ( + "{" + ",".join(f"{_canonical_string(n)}:{_canonical_value(v, depth + 1, budget)}" for n, v in members) + "}" + ) + elif isinstance(value, list | tuple): + if len(value) > _MAX_OP_COLLECTION_ENTRIES: + raise ValueError(f"malformed_op: array exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") + budget[0] += 4 + rendered = "[" + ",".join(_canonical_value(child, depth + 1, budget) for child in value) + "]" + else: + raise ValueError(f"malformed_op: op payload is not canonical JSON: {type(value).__name__} is not serializable") + if budget[0] > _MAX_OP_COST: + raise ValueError(f"malformed_op: payload exceeds the {_MAX_OP_COST}-unit cost budget") + return rendered def _canonical_op(op: dict) -> str: - cost = 0 - stack: list[tuple[Any, int]] = [(op, 0)] - while stack: - value, depth = stack.pop() - if depth > _MAX_OP_PAYLOAD_DEPTH: - raise ValueError(f"payload_too_deep: op payload nests deeper than {_MAX_OP_PAYLOAD_DEPTH} levels") - cost += 1 - if isinstance(value, str): - cost += len(value) - elif isinstance(value, dict): - if len(value) > _MAX_OP_COLLECTION_ENTRIES: - raise ValueError(f"malformed_op: object exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") - cost += 4 + sum(len(str(key)) for key in value) - stack.extend((child, depth + 1) for child in value.values()) - elif isinstance(value, list | tuple): - if len(value) > _MAX_OP_COLLECTION_ENTRIES: - raise ValueError(f"malformed_op: array exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") - cost += 4 - stack.extend((child, depth + 1) for child in value) - else: - cost += 8 - if cost > _MAX_OP_COST: - raise ValueError(f"malformed_op: payload exceeds the {_MAX_OP_COST}-unit cost budget") - try: - return json.dumps(op, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False) - except (TypeError, ValueError) as exc: - raise ValueError(f"malformed_op: op payload is not canonical JSON: {exc}") from exc + """Compact JSON over the whole envelope: keys sorted by Unicode code point + at every depth, array order preserved, numbers rendered as ECMAScript + renders them so the digest matches the CMP A8 counterpart's.""" + return _canonical_value(op, 0, [0]) def _op_digest(op: dict) -> str: diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 4eee1c30d..6ccf5d063 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -1,4 +1,4 @@ -"""``op_id`` is bound to one canonical payload (op-vocabulary Amendment v1.6 / CMP A8). +"""``op_id`` is bound to one canonical payload (op-vocabulary Amendment v1.10 / CMP A8). The graph here is a real :class:`~comfy_cli.cql.engine.Graph` built from a one-node ``object_info``, not a hand-rolled stub. ``apply_op`` -> ``set_widget`` @@ -10,6 +10,7 @@ from __future__ import annotations import copy +import json from typing import Any import pytest @@ -87,3 +88,91 @@ def test_canonical_ignores_replay_digest_metadata(graph): ops.apply_op(applied, _op(), graph) applied["nodes"] = copy.deepcopy(workflow["nodes"]) assert ops.canonical(applied) == ops.canonical(workflow) + + +# --- Amendment v1.10: what the canonical form has to agree with ------------- + + +def test_numbers_are_rendered_the_way_ecmascript_renders_them(): + """The counterpart implementation (CMP A8) canonicalizes with + ``JSON.stringify``, so the digest only matches cross-implementation if the + numbers are spelled ECMAScript's way. Python's own float repr disagrees on + exactly the shapes a FLOAT widget produces: an integral float, negative + zero, and an exponent. + """ + assert ops._canonical_op({"v": 20.0}) == '{"v":20}' + assert ops._canonical_op({"v": -0.0}) == '{"v":0}' + assert ops._canonical_op({"v": 1e-7}) == '{"v":1e-7}' + assert ops._canonical_op({"v": 1e-6}) == '{"v":0.000001}' + assert ops._canonical_op({"v": 1e20}) == '{"v":100000000000000000000}' + assert ops._canonical_op({"v": 1e21}) == '{"v":1e+21}' + assert ops._canonical_op({"v": 1.5}) == '{"v":1.5}' + assert ops._canonical_op({"v": 5e-324}) == '{"v":5e-324}' + + +def test_a_float_widget_relayed_through_js_digests_the_same(graph): + """A FLOAT op whose value is integral comes back from a JS relay as an int. + Both spellings have to digest identically, or the identical redelivery is + rejected as ``op_id_reuse``. + """ + workflow = _workflow() + as_float = _op(20.0) + ops.apply_op(workflow, as_float, graph) + relayed = _op(20) # what `JSON.parse(JSON.stringify(op))` yields + assert ops._op_digest(relayed) == ops._op_digest(as_float) + assert ops.apply_op(workflow, relayed, graph) is workflow + + +def test_non_finite_numbers_canonicalize_as_null_like_json_stringify(graph): + """``json.load`` accepts NaN/Infinity, so a document can hold one and an op + captures it in ``old`` or in the host's ``host_widgets_values``. The earlier + ``allow_nan=False`` made every such write raise; ``JSON.stringify`` renders + them as ``null``, and matching that is both cross-implementation correct and + what un-breaks overwriting a NaN widget. + """ + assert ops._canonical_op({"v": float("nan")}) == '{"v":null}' + assert ops._canonical_op({"v": float("inf")}) == '{"v":null}' + assert ops._canonical_op({"v": [float("-inf")]}) == '{"v":[null]}' + + workflow = _workflow() + workflow["nodes"][0]["widgets_values"] = [float("nan")] + workflow, op = ops.set_widget(workflow, graph, 7, "steps", 30) + assert workflow["nodes"][0]["widgets_values"] == [30] + assert workflow["_applied_op_digests"][op["op_id"]] == ops._op_digest(op) + + +def test_a_lone_surrogate_digests_instead_of_dying_on_the_utf8_encode(): + """``json.loads('"\\ud800"')`` produces a lone surrogate, which cannot be + UTF-8 encoded at all. ES2019 well-formed stringify escapes it; so do we, so + the digest stays total instead of raising a bare ``UnicodeEncodeError`` + outside the ``malformed_op:`` contract callers classify errors by. + """ + op = {"v": json.loads('"\\ud800"')} + assert ops._canonical_op(op) == '{"v":"\\ud800"}' + assert len(ops._op_digest(op)) == 64 + + +def test_ordinary_large_payloads_are_not_rejected_by_the_canonicalization_bounds(): + """The bounds exist to stop a runaway payload, not to cap a real edit. The + first pair (4,096 entries / 262,144 cost units) rejected edits that used to + succeed: ``clear``/``reset_doc`` enumerate every node id, ``delete_node`` + on a hub node enumerates every incident link, and a prompt value runs past + 256K characters. + """ + assert len(ops._op_digest({"removed_nodes": list(range(20_000))})) == 64 + assert len(ops._op_digest({"removed_links": [[i, 1, 0, 2, 0, "T"] for i in range(10_000)]})) == 64 + assert len(ops._op_digest({"value": "x" * 1_000_000})) == 64 + + +def test_canonicalization_still_refuses_a_runaway_payload(): + nested: Any = "leaf" + for _ in range(ops._MAX_OP_PAYLOAD_DEPTH + 2): + nested = [nested] + with pytest.raises(ValueError, match="^payload_too_deep:"): + ops._op_digest({"v": nested}) + with pytest.raises(ValueError, match="^malformed_op: array exceeds"): + ops._op_digest({"v": [0] * (ops._MAX_OP_COLLECTION_ENTRIES + 1)}) + with pytest.raises(ValueError, match="cost budget$"): + ops._op_digest({"v": ["x" * 4096] * 16_384}) + with pytest.raises(ValueError, match="^malformed_op: op payload is not canonical JSON:"): + ops._op_digest({"v": object()}) From d55119031668b4d24fa658c1a68d2109265c3a18 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 24 Oct 2026 02:16:00 +0000 Subject: [PATCH 07/30] fix(workflow): gate op-id reuse on the deferred queue, and validate the ledger before mutating MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three defects in `apply_op`'s entry, all of which let a reused `op_id` past the gate or damaged the document after a handler had already written it. **A deferred write escaped the gate entirely.** The gate read `_applied_ops` only, and a `set_widget` waiting for a selector to reveal its target sits in `_deferred_widget_ops` and nowhere else; the digest computed for it was discarded when it deferred. A second op carrying the same `op_id` and a different payload therefore went straight through — it overwrote the pending entry or applied at once, and the tail's `deferred.pop(op_id)` then dropped the original. No `op_id_reuse` was raised, so two replicas that received the pair in different orders diverged silently. The gate now compares against the queued payload's digest too. **The replay bookkeeping was trusted.** `_applied_op_digests` is stripped on write but never checked on load, and `op_id` is whatever the envelope carried. A null, list or string ledger, or a list/dict `op_id`, raised `TypeError` (or `AttributeError`, on the reuse branch's `(… or {}).get` for a truthy non-dict) in the tail — *after* the handler had written the document and appended to `_applied_ops`, outside the rollback, leaving the op half-committed with its deferred cleanup skipped. All three are now `malformed_op` before anything mutates. The presence test is membership rather than truthiness: an explicit `null` is present, and `setdefault` hands back that `None` rather than a fresh dict. **`setdefault("_applied_ops", [])` ran before the digest.** Canonicalization rejecting a first-seen op then left a document that had arrived with no ledger carrying `_applied_ops: []`, contradicting the amendment's "rejects before mutation" wording — the `setdefault` sat outside the try block whose cleanup removes a freshly created list. The digest is now computed first, with `workflow.get` for the membership check. The legacy list-only path is deliberately unchanged, including that it returns *without* digesting the replayed payload: a non-canonical replay must still be the documented no-op rather than a new error. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538097 https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538101 https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538108 --- comfy_cli/workflow_ops.py | 56 ++++++++++++--- .../test_dynamic_combo_other_option_widget.py | 35 +++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 71 +++++++++++++++++++ 3 files changed, 154 insertions(+), 8 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 769e519fc..fcdd5f834 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3158,16 +3158,56 @@ def apply_specs( def apply_op(workflow: dict, op: dict, graph) -> dict: """Replay one op onto ``workflow`` in place and return it. Idempotent: an op whose ``op_id`` was already applied is a no-op only for one payload.""" - had_applied_ops = "_applied_ops" in workflow - applied = workflow.setdefault("_applied_ops", []) - if op["op_id"] in applied: - recorded = (workflow.get("_applied_op_digests") or {}).get(op["op_id"]) + # Validate the replay bookkeeping BEFORE anything mutates. All three values + # arrive from untrusted JSON — ``_applied_op_digests`` and ``_applied_ops`` + # are stripped on write but never checked on load, and ``op_id`` is whatever + # the envelope carried — and all three are indexed by the tail below. Left + # unchecked, a null/list/string ledger or a list-valued ``op_id`` raises + # ``TypeError``/``AttributeError`` AFTER the handler has written the + # document and appended to ``_applied_ops``, outside the rollback: a + # half-committed op whose deferred cleanup never ran. + op_id = op["op_id"] + if not isinstance(op_id, str): + raise ValueError(f"malformed_op: op_id must be a string, got {type(op_id).__name__}") + # Membership, not truthiness: an explicit ``null`` is PRESENT, and the + # ``setdefault`` in the tail below would hand back that ``None`` rather than + # a fresh dict. + if "_applied_op_digests" in workflow and not isinstance(workflow["_applied_op_digests"], dict): + raise ValueError("malformed_op: _applied_op_digests must be an object keyed by op_id") + if "_applied_ops" in workflow and not isinstance(workflow["_applied_ops"], list): + raise ValueError("malformed_op: _applied_ops must be an array of op_ids") + recorded_digests = workflow.get("_applied_op_digests") + recorded_ops = workflow.get("_applied_ops") + if op_id in (recorded_ops or ()): + recorded = (recorded_digests or {}).get(op_id) if recorded is None: + # A legacy list-only ledger keeps its historical duplicate + # behaviour, and deliberately WITHOUT digesting the payload first: + # a replay whose envelope is not canonical must still be the + # documented no-op rather than a ``malformed_op``. return workflow if recorded != _op_digest(op): - raise ValueError(f"op_id_reuse: op_id {op['op_id']!r} was already applied with a different payload") + raise ValueError(f"op_id_reuse: op_id {op_id!r} was already applied with a different payload") return workflow + # Digest BEFORE the ``setdefault`` below, so a first-seen op that + # canonicalization rejects leaves a document that had no ledger exactly as + # it found it — which is what the amendment's "rejects before mutation" + # wording promises. digest = _op_digest(op) + # A deferred ``set_widget`` never reached ``_applied_ops`` — it waits in + # ``_deferred_widget_ops`` until a selector reveals its target — so gating + # on the applied list alone lets a SECOND op carrying the same ``op_id`` and + # a different payload straight through: it overwrites the pending entry (or + # applies at once), and the tail's ``deferred.pop`` then drops the original. + # No ``op_id_reuse`` is raised, so two replicas that received the pair in + # different orders diverge silently. + queued = workflow.get("_deferred_widget_ops") + waiting = queued.get(op_id) if isinstance(queued, dict) else None + # Cannot raise: a queued op was canonicalized on the way in. + if isinstance(waiting, dict) and _op_digest(waiting) != digest: + raise ValueError(f"op_id_reuse: op_id {op_id!r} is already deferred with a different payload") + had_applied_ops = "_applied_ops" in workflow + workflow.setdefault("_applied_ops", []) kind = op["op"] if kind != "insert_workflow" and "definitions" in op: raise ValueError(f"malformed_op: {kind} does not accept definitions") @@ -3225,11 +3265,11 @@ def apply_op(workflow: dict, op: dict, graph) -> dict: # binding above is stale for that kind and the reset's own op_id would be # written into a discarded list. Re-read, so a re-delivered reset_doc is a # no-op rather than a second wipe. - workflow.setdefault("_applied_ops", []).append(op["op_id"]) - workflow.setdefault("_applied_op_digests", {})[op["op_id"]] = digest + workflow.setdefault("_applied_ops", []).append(op_id) + workflow.setdefault("_applied_op_digests", {})[op_id] = digest deferred = workflow.get("_deferred_widget_ops") if isinstance(deferred, dict): - deferred.pop(op["op_id"], None) + deferred.pop(op_id, None) if not deferred: workflow.pop("_deferred_widget_ops", None) if kind == "set_widget": diff --git a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py index 8d8ad3781..fa8b15e6c 100644 --- a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py +++ b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py @@ -598,3 +598,38 @@ def test_a_deferred_write_is_bound_to_its_canonical_payload_once_applied(graph): with pytest.raises(ValueError, match="^op_id_reuse:"): workflow_ops.apply_op(wf, changed, graph) assert wf == before + + +def test_a_second_payload_on_a_deferred_op_id_is_refused_rather_than_overwriting_it(graph): + """The reuse gate used to read ``_applied_ops`` only. A deferred write sits + in ``_deferred_widget_ops`` and nowhere else, so a second op carrying the + same ``op_id`` and a different payload went straight past the gate: it + overwrote the pending entry (or applied at once), and the tail's + ``deferred.pop`` then dropped the original. No ``op_id_reuse`` was raised, + so two replicas that received the pair in different orders diverged. + """ + wf, node_id = _fresh(graph) + hidden_write = workflow_ops._new_op( + "set_widget", + "agent-a", + 1, + node_id=node_id, + widget="model.prompt_expansion_mode", + value="quality", + ) + workflow_ops.apply_op(wf, hidden_write, graph) + assert hidden_write["op_id"] in wf["_deferred_widget_ops"] + + changed = copy.deepcopy(hidden_write) + changed["value"] = "balanced" + before = copy.deepcopy(wf) + with pytest.raises(ValueError, match="^op_id_reuse:"): + workflow_ops.apply_op(wf, changed, graph) + assert wf == before + # The original is still the queued payload, so revealing the target applies + # what was actually sent first. + assert wf["_deferred_widget_ops"][hidden_write["op_id"]]["value"] == "quality" + + # An identical redelivery while deferred stays a no-op on the queue. + workflow_ops.apply_op(wf, copy.deepcopy(hidden_write), graph) + assert wf["_deferred_widget_ops"][hidden_write["op_id"]]["value"] == "quality" diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 6ccf5d063..3e4a379da 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -176,3 +176,74 @@ def test_canonicalization_still_refuses_a_runaway_payload(): ops._op_digest({"v": ["x" * 4096] * 16_384}) with pytest.raises(ValueError, match="^malformed_op: op payload is not canonical JSON:"): ops._op_digest({"v": object()}) + + +# --- Amendment v1.10: rejecting before mutation ----------------------------- + + +def test_a_rejected_first_seen_op_leaves_no_ledger_behind(graph): + """ "Rejects before mutation" has to include the ledger itself: a document + that arrived without ``_applied_ops`` must not come back carrying an empty + one because canonicalization refused the op. + """ + workflow = _workflow() + before = copy.deepcopy(workflow) + deep = _op() + deep["value"] = [["x"] * 1] + for _ in range(ops._MAX_OP_PAYLOAD_DEPTH + 2): + deep["value"] = [deep["value"]] + with pytest.raises(ValueError, match="^payload_too_deep:"): + ops.apply_op(workflow, deep, graph) + assert workflow == before + assert "_applied_ops" not in workflow + + +@pytest.mark.parametrize( + ("ledger", "message"), + [ + (None, "^malformed_op: _applied_op_digests must be an object"), + ([], "^malformed_op: _applied_op_digests must be an object"), + ("{}", "^malformed_op: _applied_op_digests must be an object"), + ], +) +def test_a_malformed_digest_ledger_is_refused_before_the_handler_runs(graph, ledger, message): + """The ledger is stripped on write but never checked on load. Indexing it in + ``apply_op``'s tail raised ``TypeError`` after the handler had already + written the document and appended to ``_applied_ops`` — outside the + rollback, so the op stayed half-committed. + """ + workflow = _workflow() + workflow["_applied_op_digests"] = ledger + before = copy.deepcopy(workflow) + with pytest.raises(ValueError, match=message): + ops.apply_op(workflow, _op(), graph) + assert workflow == before + + +def test_a_truthy_non_dict_ledger_is_refused_on_the_reuse_branch_too(graph): + workflow = _workflow() + applied = _op() + ops.apply_op(workflow, applied, graph) + workflow["_applied_op_digests"] = "not a mapping" + with pytest.raises(ValueError, match="^malformed_op: _applied_op_digests must be an object"): + ops.apply_op(workflow, applied, graph) + + +@pytest.mark.parametrize("op_id", [["a"], {"a": 1}, 7, None]) +def test_a_non_string_op_id_is_refused_before_the_handler_runs(graph, op_id): + workflow = _workflow() + before = copy.deepcopy(workflow) + bad = _op() + bad["op_id"] = op_id + with pytest.raises(ValueError, match="^malformed_op: op_id must be a string"): + ops.apply_op(workflow, bad, graph) + assert workflow == before + + +def test_a_malformed_applied_ops_list_is_refused_before_the_handler_runs(graph): + workflow = _workflow() + workflow["_applied_ops"] = {"not": "a list"} + before = copy.deepcopy(workflow) + with pytest.raises(ValueError, match="^malformed_op: _applied_ops must be an array"): + ops.apply_op(workflow, _op(), graph) + assert workflow == before From bd356f89c2649d50b6b2a769cddab9b6bd49dbb2 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 24 Oct 2026 02:16:32 +0000 Subject: [PATCH 08/30] fix(workflow): bind the enriched envelope without failing an op that already applied MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `_set_widget_impl` finishes a promoted / `legacy_primitive` `set_widget` after `apply_op` returns, because the host's materialized `host_widgets_values` can only be read back out of the document the write produced. It then rebound the ledger entry with a bare index and an unguarded digest, both of which could fail after the document had changed: * `workflow["_applied_op_digests"][op["op_id"]] = …` raises `KeyError` whenever `apply_op` took an early-return path and so never created the ledger — a deferred write, or a legacy list-only replay. * the enriched envelope carries the host's full positional array, which the pre-mutation digest never saw. It comes out of the *document*, so it can hold a NaN/Infinity (`json.load` accepts both), a lone surrogate, or more volume than the bounds allow, none of which the op payload itself contained. The digest then raised for an op the document had already accepted: the caller saw a failure for a write that happened, never got the op back to broadcast, and `set_widget`'s `ValueError` fallback could attempt a second write. `_rebind_op_digest` corrects the entry only when it is this call's own — recognized by comparing against the digest `apply_op` actually recorded, not by the key's presence, so a deferred or duplicate entry is left alone — and keeps the pre-enrichment digest when the enriched envelope is not canonical. The document is already written by then, so holding a digest that a redelivery will refuse in the *pre-mutation* duplicate branch is strictly better than reporting failure for an applied op. `_retry_deferred_widget_ops` had the same ordering problem on a smaller scale and now digests before the write, dropping an uncanonical queued payload the way it already drops a non-dict entry. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538095 --- comfy_cli/workflow_ops.py | 69 +++++++++++++++-- tests/comfy_cli/test_op_id_reuse_contract.py | 78 ++++++++++++++++++++ 2 files changed, 141 insertions(+), 6 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index fcdd5f834..34ada78dc 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -233,6 +233,50 @@ def _op_digest(op: dict) -> str: return hashlib.sha256(_canonical_op(op).encode("utf-8")).hexdigest() +def _applied_digest(op: dict) -> str | None: + """The digest :func:`apply_op` would have recorded for ``op``, or ``None`` + when the payload is not canonical, so nothing recorded one.""" + try: + return _op_digest(op) + except ValueError: + return None + + +def _rebind_op_digest(workflow: dict, op: dict, applied: str | None) -> None: + """Re-bind ``op_id`` to the digest of the *enriched* envelope. + + ``_set_widget_impl`` finishes a promoted / legacy-primitive op AFTER + :func:`apply_op` returns — the host's materialized ``host_widgets_values`` + can only be read back out of the document the write produced — so the ledger + otherwise holds the pre-enrichment digest while the caller broadcasts the + enriched payload, and a redelivery of what was actually sent is rejected as + ``op_id_reuse``. + + Nothing happens in the two cases where correcting it would be wrong: + + * the op was DEFERRED, or was a duplicate, so the ledger entry either does + not exist or belongs to a different payload. Detected by comparing against + the digest ``apply_op`` actually wrote for *this* call rather than by + trusting the key's presence. + * the enriched envelope is not canonical. ``host_widgets_values`` comes out + of the document, so it can carry a NaN/Infinity, a lone surrogate or a + volume the op payload never did. The document is ALREADY written here, so + raising would report failure for an op that was applied: the caller never + gets it back to broadcast and ``set_widget``'s ``ValueError`` fallback can + attempt a second write. The pre-enrichment digest stays instead, and a + redelivery of the uncanonical envelope is refused in :func:`apply_op`'s + duplicate branch — before it can mutate anything. + """ + if applied is None: + return + digests = workflow.get("_applied_op_digests") + if not isinstance(digests, dict) or digests.get(op["op_id"]) != applied: + return + enriched = _applied_digest(op) + if enriched is not None: + digests[op["op_id"]] = enriched + + def mint_id() -> int: """A leaderless, collision-free, int-typed identity for a node or link.""" return _ID_FLOOR | random.getrandbits(52) @@ -1263,6 +1307,9 @@ def _set_widget_impl( if warnings: op["warnings"] = warnings workflow = apply_op(workflow, op, graph) + # Captured before the enrichment below mutates ``op``: it is how + # ``_rebind_op_digest`` recognizes the ledger entry as this call's own. + applied_digest = _applied_digest(op) if target.repair is not None: # The slot only exists after the repair (and the instance may sit # on a freshly forked definition): read it back from the document. @@ -1277,7 +1324,7 @@ def _set_widget_impl( # resolution is the pre-fork sibling, not the written one. written = _engine._resolve_node_path(workflow, list(target.segments), _engine._subgraph_defs_by_id(workflow)) op["promoted"]["host_widgets_values"] = _promoted.host_widgets_values(written) - workflow["_applied_op_digests"][op["op_id"]] = _op_digest(op) + _rebind_op_digest(workflow, op, applied_digest) return workflow, op if target.kind == "legacy_primitive": # A frontend-only PrimitiveNode has no catalog entry, so every @@ -1299,8 +1346,9 @@ def _set_widget_impl( **extra, ) workflow = apply_op(workflow, op, graph) + applied_digest = _applied_digest(op) op["promoted"]["host_widgets_values"] = list(src.get("widgets_values") or []) - workflow["_applied_op_digests"][op["op_id"]] = _op_digest(op) + _rebind_op_digest(workflow, op, applied_digest) return workflow, op if target.kind == "top" and target.redirected_from is not None: node_id = target.node.get("id") @@ -3291,14 +3339,23 @@ def _retry_deferred_widget_ops(workflow: dict, graph) -> None: pending.pop(op_id, None) progressed = True continue - if _apply_set_widget(workflow, op, graph) is False: - continue - workflow.setdefault("_applied_ops", []).append(op_id) # Bind the id to its canonical payload here too: a deferred write # reaches ``_applied_ops`` through this loop and never through # ``apply_op``'s tail, so without this the reuse gate would read it # as a legacy list-only entry and silently no-op a changed retry. - workflow.setdefault("_applied_op_digests", {})[op_id] = _op_digest(op) + # Digested BEFORE the write, so an uncanonical queued payload — only + # reachable from a hand-edited document, since ``apply_op`` + # canonicalizes on the way in — is dropped like the non-dict entry + # above instead of raising half-way through its own apply. + digest = _applied_digest(op) + if digest is None: + pending.pop(op_id, None) + progressed = True + continue + if _apply_set_widget(workflow, op, graph) is False: + continue + workflow.setdefault("_applied_ops", []).append(op_id) + workflow.setdefault("_applied_op_digests", {})[op_id] = digest pending.pop(op_id, None) progressed = True if not progressed: diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 3e4a379da..7e8411861 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -247,3 +247,81 @@ def test_a_malformed_applied_ops_list_is_refused_before_the_handler_runs(graph): with pytest.raises(ValueError, match="^malformed_op: _applied_ops must be an array"): ops.apply_op(workflow, _op(), graph) assert workflow == before + + +# --- Amendment v1.10: the enriched envelope --------------------------------- + + +def _primitive_canvas(value="old prompt") -> dict: + """A frontend-only ``PrimitiveNode``: no catalog entry, so ``set_widget`` + takes the ``legacy_primitive`` path that enriches the op with the host's + positional array AFTER ``apply_op`` has already recorded a digest. + """ + return { + "nodes": [ + { + "id": 51, + "type": "PrimitiveNode", + "outputs": [{"name": "STRING", "type": "STRING", "links": [], "widget": {"name": "text"}}], + "widgets_values": [value], + } + ], + "links": [], + } + + +def test_the_ledger_binds_the_enriched_envelope_the_caller_broadcasts(graph): + """``_set_widget_impl`` finishes the op after ``apply_op`` returns, because + ``host_widgets_values`` can only be read back out of the document the write + produced. If the ledger kept the pre-enrichment digest, a redelivery of the + payload that was actually broadcast would be rejected as ``op_id_reuse``. + """ + workflow, op = ops.set_widget(_primitive_canvas(), graph, 51, "value", "a lighthouse at dusk") + assert op["promoted"]["host_widgets_values"] == ["a lighthouse at dusk"] + assert workflow["_applied_op_digests"][op["op_id"]] == ops._op_digest(op) + # The broadcast envelope round-trips as the documented no-op... + assert ops.apply_op(workflow, copy.deepcopy(op), graph) is workflow + # ...and the same id with a changed payload is still refused. + changed = copy.deepcopy(op) + changed["value"] = "a lighthouse at dawn" + with pytest.raises(ValueError, match="^op_id_reuse:"): + ops.apply_op(workflow, changed, graph) + + +def test_a_nan_host_widget_no_longer_fails_an_op_that_already_applied(graph): + """The enriched digest runs after the write has committed, so raising there + reported failure for an op the document had already accepted: the caller + never got it back to broadcast and ``set_widget``'s ``ValueError`` fallback + could attempt a second write. + """ + workflow, op = ops.set_widget(_primitive_canvas(float("nan")), graph, 51, "value", "lighthouse") + assert workflow["nodes"][0]["widgets_values"] == ["lighthouse"] + assert workflow["_applied_op_digests"][op["op_id"]] == ops._op_digest(op) + + +def test_rebinding_a_digest_is_inert_when_the_entry_is_not_this_calls_own(): + """The three cases ``_rebind_op_digest`` must leave alone: no ledger at all + (the op deferred, so nothing recorded it), an entry belonging to a different + payload (a duplicate), and an uncanonical enriched envelope (the document is + already written, so raising is worse than keeping the older digest). + """ + op = _op() + applied = ops._op_digest(op) + enriched = dict(op, promoted={"host_widgets_values": ["x"]}) + + no_ledger: dict = {} + ops._rebind_op_digest(no_ledger, enriched, applied) + assert no_ledger == {} + + someone_elses = {"_applied_op_digests": {op["op_id"]: "a" * 64}} + ops._rebind_op_digest(someone_elses, enriched, applied) + assert someone_elses["_applied_op_digests"][op["op_id"]] == "a" * 64 + + uncanonical = dict(enriched, promoted={"host_widgets_values": [object()]}) + ours = {"_applied_op_digests": {op["op_id"]: applied}} + ops._rebind_op_digest(ours, uncanonical, applied) + assert ours["_applied_op_digests"][op["op_id"]] == applied + + ours = {"_applied_op_digests": {op["op_id"]: applied}} + ops._rebind_op_digest(ours, enriched, applied) + assert ours["_applied_op_digests"][op["op_id"]] == ops._op_digest(enriched) From 4bdcc29e6ce2deaf97e36f9430a6fc6bdee254be Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 24 Oct 2026 02:16:46 +0000 Subject: [PATCH 09/30] docs(op-vocabulary): renumber the canonical-identity amendment to v1.10 and append it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new section was labelled "Amendment v1.6", which §15 already owns for the `set_node_field` amendment, so every "op-vocabulary Amendment v1.6" reference in the test docstrings pointed at two different contracts. It was also undated and wedged between §2 and §3 rather than appended at the end, which is what §9 says a post-freeze amendment must be. It is now §19, Amendment v1.10, dated 2026-10-24, appended after §18. §2's identity bullet cites it instead of restating it, and the one test docstring naming v1.6 for this contract is updated; the three remaining v1.6 references in the tree are all `set_node_field` and are correct as they stand. The body is also expanded to say what the canonical form actually requires now that it has to match `JSON.stringify` byte-for-byte — ECMAScript number rendering, non-finite as `null`, lone surrogates escaped — and records the raised bounds with why the first pair was too tight. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/908#discussion_r4365538103 --- docs/op-vocabulary-v1.md | 98 +++++++++++++++++-- .../test_dynamic_combo_other_option_widget.py | 2 +- 2 files changed, 92 insertions(+), 8 deletions(-) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index ff9364633..bd1c93c07 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -338,15 +338,16 @@ local model can need it. * Every op carries `op_id`: uuid4 hex, minted by the **creator, before dispatch** (`_new_op`). Receivers never regenerate or rewrite an `op_id`. -* `apply_op` records applied `op_id`s in `_applied_ops` and records `sha256(canonical_op)` in `_applied_op_digests`. An identical retry is a no-op; reuse with a different canonical payload rejects with `op_id_reuse`. Legacy documents with only the list retain their historical duplicate behavior. **Uniqueness scope is +* `apply_op` records applied `op_id`s in the document's `_applied_ops` list and + their canonical digests in `_applied_op_digests`. An identical retry is a + no-op; the same `op_id` carrying a different canonical payload rejects with + `op_id_reuse`. A legacy document with only the list keeps its historical + duplicate behavior. See **Amendment v1.10** for the canonical form, the + bounds and the ledger contract. **Uniqueness scope is PER-WORKFLOW**: the same `op_id` can exist in two different workflow documents without interaction; within one document each op applies exactly once. -* `_applied_ops` (and `_widget_stamps`) are apply-time bookkeeping, stripped - before serialization to disk (`strip_internal`). - -## Amendment v1.6 — canonical op identity - -`op_id` identifies one immutable semantic-op envelope. The canonical form is compact UTF-8 JSON over the whole envelope, with object keys sorted by Unicode code point at every depth and array order preserved. The replay ledger records its lowercase SHA-256 digest. Reusing an `op_id` with a different canonical payload rejects before mutation with `op_id_reuse`; an identical retry remains a no-op. Canonicalization is bounded to 64 levels, 4,096 entries per collection, and 262,144 approximate cost units. This mirrors comfy-multi-player schema Amendment A8. The asymmetric case is load-bearing: `{value: 25}` followed by the same `op_id` carrying `{value: 30}` rejects, while key insertion order is immaterial. +* `_applied_ops`, `_applied_op_digests` (and `_widget_stamps`) are apply-time + bookkeeping, stripped before serialization to disk (`strip_internal`). ## 3. Conflict rules @@ -1229,3 +1230,86 @@ v1.9. **No change to §§2-8.** No op kind was added, removed, or re-scoped; `FROZEN_OPS` / `DEFERRED_OPS` / `BATCHABLE_OPS` are untouched. Downstream repos pinning this document by SHA move the SHA together with their comfy-cli pin. + +## 19. Amendment v1.10 — 2026-10-24 (canonical op identity: `op_id` binds one payload) + +**`op_id` identifies one immutable semantic-op envelope, not just one delivery.** +Before this amendment `apply_op` dropped any op whose `op_id` was already in +`_applied_ops` without looking at the payload, so a sender that reused an id +with a changed payload had its second edit silently discarded — and two +replicas that received the pair in different orders ended up with different +documents and no error on either side. This mirrors comfy-multi-player schema +**Amendment A8**; the two implementations must agree byte-for-byte on the +canonical form, because the digest is the only thing that distinguishes an +identical retry from reuse. + +### 19.1 The canonical form + +Compact JSON over the **whole envelope**: + +* object keys sorted by **Unicode code point** at every depth; array order + preserved; no insignificant whitespace (`,`/`:` separators, no spaces); +* **numbers rendered as ECMAScript renders them** (`Number::toString`), not as + Python's float repr does. An integral float is `20`, not `20.0`; negative zero + is `0`; an exponent is `1e-7`, not `1e-07`. This is load-bearing rather than + cosmetic: the counterpart builds the canonical form with `JSON.stringify`, so + without it a FLOAT widget op relayed through JS digests differently on the two + sides and an identical redelivery is rejected as `op_id_reuse`; +* **every non-finite number renders as `null`**, which is what `JSON.stringify` + does. The alternative — rejecting the op — made a widget whose *current* value + is `NaN`/`Infinity` impossible to overwrite, because the op captures that + value in `old` (and `json.load` accepts both spellings on the way in); +* a **lone surrogate** renders as a `\udXXX` escape, matching ES2019 + well-formed `JSON.stringify`. Emitted raw it cannot be UTF-8 encoded at all, + so the digest died with a bare `UnicodeEncodeError` outside the + `malformed_op:` prefix callers classify errors by. + +The ledger records the lowercase SHA-256 hex digest of that string. + +### 19.2 The ledger contract + +* `_applied_op_digests` maps `op_id` → digest, beside `_applied_ops`. Both are + stripped by `canonical()` and `strip_internal()`, and `reset_doc` clears both + as one history barrier. +* **Rejects before mutation.** `op_id`, `_applied_ops` and `_applied_op_digests` + all arrive from untrusted JSON and are all validated before any handler runs: + a non-string `op_id`, or a ledger that is not an object/array, is + `malformed_op`. So is a payload canonicalization refuses. A document that + arrived without a ledger is never left carrying an empty one by a rejected op. +* **A deferred op is already bound.** A `set_widget` waiting in + `_deferred_widget_ops` for a selector to reveal its target has not reached + `_applied_ops`, so the gate checks the deferred queue too; a second payload on + that `op_id` rejects instead of overwriting the pending entry. +* **The enriched envelope is what is bound.** A promoted or `legacy_primitive` + `set_widget` only learns the host's materialized `host_widgets_values` by + reading back the document the write produced, so the ledger entry is corrected + to the envelope the caller actually broadcasts. If that enriched envelope is + not canonical the earlier digest stands: the document is already written, and + reporting failure for an applied op is worse than holding a digest a + redelivery will refuse in the pre-mutation branch. +* **Legacy documents are untouched.** One carrying `_applied_ops` and no + `_applied_op_digests` keeps the historical drop-the-duplicate behavior, and + deliberately without digesting the replayed payload first — a non-canonical + replay must still be the documented no-op rather than a new error. + +### 19.3 Bounds + +Canonicalization is bounded to **64 levels of nesting**, **1,048,576 entries per +collection** and **33,554,432 approximate cost units**. These exist only so a +hostile or runaway payload cannot pin a replica inside canonicalization; every +ordinary op has to pass, because the digest is computed on every apply and not +only on a reuse comparison. The first pair of bounds (4,096 entries / 262,144 +units) was tight enough to reject real edits: `clear` and `reset_doc` enumerate +every node id in `removed_nodes`, a `delete_node` on a hub node enumerates every +incident link, and a prompt value — or the `old` value an op captures — runs +past 256K characters routinely. + +The asymmetric case is the one to keep in mind: `{value: 25}` followed by the +same `op_id` carrying `{value: 30}` rejects, while the same payload with its keys +in a different insertion order is an ordinary no-op. + +**No change to §§1, 3-8.** No op kind was added, removed, or re-scoped; +`FROZEN_OPS` / `DEFERRED_OPS` / `BATCHABLE_OPS` are untouched. §2's identity +bullet now cites this section. Downstream repos pinning this document by SHA +move the SHA together with their comfy-cli pin, and must move their CMP A8 pin +with it. diff --git a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py index fa8b15e6c..fa91a98f8 100644 --- a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py +++ b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py @@ -570,7 +570,7 @@ def test_missing_nested_selector_uses_the_active_outer_options_default(): def test_a_deferred_write_is_bound_to_its_canonical_payload_once_applied(graph): """A deferred write reaches ``_applied_ops`` through the retry loop, not through ``apply_op``'s tail, so the op-id/payload binding (op-vocabulary - Amendment v1.6) has to be recorded there too. Without it the reuse gate + Amendment v1.10) has to be recorded there too. Without it the reuse gate sees a list-only entry and silently no-ops a changed-payload retry.""" wf, node_id = _fresh(graph) hidden_write = workflow_ops._new_op( From 28869741f22f825d62886e2c68be258bfb59b294 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 24 Oct 2026 02:26:40 +0000 Subject: [PATCH 10/30] fix(workflow): clear the public-repo hygiene check, and pin the key sort to code points MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `public-repo-hygiene` failed on the new `_es_number` docstring: it reads the hyphenated spec name as an internal ticket id (`[A-Z]+-\d+`). Reworded to name the algorithm without the spec number. The upstream fix is an entry in that check's org-wide acronym allowlist, which is deliberately not editable from a caller repo, so that is filed as a hypothesis rather than done here. While in the amendment: the key sort is now stated to be by Unicode code point rather than by whatever `Object.keys(...).sort()` does, which is the same caveat §8.1 already records for `actor` and `op_id`. Measured: for the keys U+1F600 and U+FF00, JS's default comparator yields `["\u{1F600}", "＀"]` and code-point order yields the reverse, so the two canonical forms would disagree. Only a dict widget with non-ASCII keys can reach it, because every key an op envelope carries is ASCII, but it is cheaper to pin than to rediscover. New test: `test_object_keys_sort_by_code_point_not_by_utf16_code_unit`. --- comfy_cli/workflow_ops.py | 5 +++-- docs/op-vocabulary-v1.md | 8 +++++++- tests/comfy_cli/test_op_id_reuse_contract.py | 11 +++++++++++ 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 34ada78dc..004bf9f09 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -107,8 +107,9 @@ def _es_number(value: float) -> str: ``repr`` is still the input: it is the shortest round-tripping decimal, the same digit string ECMAScript's algorithm starts from. Only the rendering of - that digit string differs, and this reimplements it (ECMA-262 - ``Number::toString``, the ``k``/``n``/``s`` case analysis). + that digit string differs, and this reimplements it: the ECMAScript + ``Number::toString`` algorithm, including its ``k``/``n``/``s`` case + analysis for when to use fixed versus exponential notation. """ if value == 0: # also folds -0.0, which ECMAScript renders as "0" return "0" diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index bd1c93c07..547d5ed71 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1248,7 +1248,13 @@ identical retry from reuse. Compact JSON over the **whole envelope**: * object keys sorted by **Unicode code point** at every depth; array order - preserved; no insignificant whitespace (`,`/`:` separators, no spaces); + preserved; no insignificant whitespace (`,`/`:` separators, no spaces). The + same caveat as 8.1 applies: for ASCII, JS UTF-16 `<` agrees with code-point + order, but above the Basic Multilingual Plane it does not, so an + implementation must sort by code point and not rely on + `Object.keys(...).sort()`'s default comparator. Every key an op envelope + carries today is ASCII, so this only bites a dict widget whose own keys are + not; * **numbers rendered as ECMAScript renders them** (`Number::toString`), not as Python's float repr does. An integral float is `20`, not `20.0`; negative zero is `0`; an exponent is `1e-7`, not `1e-07`. This is load-bearing rather than diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 7e8411861..01513af9f 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -110,6 +110,17 @@ def test_numbers_are_rendered_the_way_ecmascript_renders_them(): assert ops._canonical_op({"v": 5e-324}) == '{"v":5e-324}' +def test_object_keys_sort_by_code_point_not_by_utf16_code_unit(): + """§8.1's caveat applies to the key sort too: for ASCII, JS UTF-16 ``<`` + agrees with code-point order, but above the Basic Multilingual Plane it does + not. ``Object.keys(...).sort()`` puts U+1F600 before U+FF00; code-point + order is the other way round, and code-point order is what the amendment + pins. Only a dict widget whose own keys are non-ASCII can reach this, since + every key an op envelope carries is ASCII. + """ + assert ops._canonical_op({"\U0001f600": 1, "\uff00": 2}) == '{"\uff00":2,"\U0001f600":1}' + + def test_a_float_widget_relayed_through_js_digests_the_same(graph): """A FLOAT op whose value is integral comes back from a JS relay as an int. Both spellings have to digest identically, or the identical redelivery is From e86f7506741f8cc7aa652aa47f93aeee9d17c5a8 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 01:34:44 +0000 Subject: [PATCH 11/30] fix(workflow): mirror comfy-multi-player's op payload bounds instead of re-deriving them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `_MAX_OP_COLLECTION_ENTRIES` / `_MAX_OP_COST` were widened here to 1,048,576 / 33,554,432 while `comfy-multi-player` — the one shared op/validation package — fixes `MAX_COLLECTION_ENTRIES` / `MAX_OP_COST` at 4,096 / 262,144 in `src/limits.ts` at 221b2b2e470c79afaface24b1edcb53cdafc8922. An op between the two bounds applied here and was then refused by the shared package as `malformed_op`: two implementations of the same validation drifting apart, which is the failure the single-package design exists to prevent. Both constants now mirror the canonical values, cited by SHA rather than by branch; `_MAX_OP_PAYLOAD_DEPTH` already matched at 64. The widening's stated justification does not survive measurement. It rested on "the digest is now computed on every apply rather than only on a reuse comparison", but that is equally true of CMP: `applyOps` calls `opDigest` -> `canonicalJson` -> `opBoundsRefusal` on the whole envelope BEFORE its dedupe gate (`applier.ts:248`), under the tight bound. So a looser bound here never rescued an edit — it only moved where an oversized op fails, to after this side had already accepted it. The three edits said to need the extra room were measured against the shared values, and none is reachable by anything observed: * `clear` / `reset_doc` bind at 4,097 nodes in one document (a 4,096-node `clear` costs 36,986 of the 262,144 units — the entry cap binds first). * a hub `delete_node` binds at 4,097 incident links on a single node; `removed_links` is a flat list of link ids, so the same cap applies. * a widget string binds at 131,064 characters when the op also captures an equal-sized `old` (262,133 without one) — a 128 KiB value in one widget. For scale: the widest op this vocabulary mints from a real workflow fixture in this repo measures 1,556 cost units over 13 entries, under 1% of the budget, and the largest workflow among those fixtures has 11 nodes. No measured case legitimately exceeds the shared bound, so nothing is recorded as a cross-repo question; if one ever appears, widen it in `comfy-multi-player` and move this pin rather than re-deriving a looser budget here. Tests: `test_ordinary_large_payloads_are_not_rejected_by_the_canonicalization_bounds` no longer asserts the old, now-wrong bound (it claimed 20,000 `removed_nodes`, 10,000 `removed_links` and a 1,000,000-char value must pass — all three are refused by the shared package); it now exercises the same three shapes at a thousand entries and 60K chars, far past anything observed. Two new cases pin the mirrored constants and the exact thresholds, and the runaway-payload case's cost probe is re-pointed to 64 x 4,096-char strings so it still reaches the cost branch instead of tripping the entry cap first. All three are red on the parent. --- comfy_cli/workflow_ops.py | 27 ++++++--- docs/op-vocabulary-v1.md | 35 ++++++++--- tests/comfy_cli/test_op_id_reuse_contract.py | 64 +++++++++++++++++--- 3 files changed, 98 insertions(+), 28 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index a92c5e280..80ae9880c 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -76,17 +76,24 @@ # frontend counter ids), always inside JS Number.MAX_SAFE_INTEGER. _ID_FLOOR = 1 << 40 +# Mirrored EXACTLY from comfy-multi-player's `src/limits.ts` at +# 221b2b2e470c79afaface24b1edcb53cdafc8922 (`MAX_PAYLOAD_DEPTH` 64, +# `MAX_COLLECTION_ENTRIES` 4096, `MAX_OP_COST` 262_144) — cited by SHA, not by +# branch, because the whole point is that the two implementations agree. +# +# These are not a local policy choice. CMP's A8 canonicalizer applies the same +# budget to the whole envelope on EVERY apply, before its dedupe gate +# (`applier.ts`: `applyOps` -> `opDigest` -> `canonicalJson` -> `opBoundsRefusal`), +# so "the digest is computed on every apply" is equally true there and a looser +# bound HERE rescues nothing — it only moves where an oversized op fails, from a +# local `malformed_op` to a `malformed_op` from the shared package after +# comfy-cli already accepted the payload. Re-deriving a second, looser budget is +# exactly the validation drift the one shared op package exists to prevent. If a +# real edit ever needs more room, widen it in comfy-multi-player and move this +# pin; never widen it here alone. _MAX_OP_PAYLOAD_DEPTH = 64 -# Bounded only so a hostile or runaway payload cannot pin a replica inside -# canonicalization. Every ORDINARY op has to pass, because the digest is now -# computed on every apply rather than only on a reuse comparison, and the first -# bounds (4,096 entries / 262,144 cost units) were tight enough to reject real -# edits: `clear` / `reset_doc` enumerate every node id in `removed_nodes`, a -# `delete_node` on a hub node enumerates every incident link, and a prompt -# widget value (or the `old` value an op captures) routinely runs past 256K -# characters. -_MAX_OP_COLLECTION_ENTRIES = 1_048_576 -_MAX_OP_COST = 33_554_432 +_MAX_OP_COLLECTION_ENTRIES = 4096 +_MAX_OP_COST = 262_144 #: Any surrogate code point in a Python ``str`` is a LONE surrogate — astral #: characters are single code points there — so matching the whole block is diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index f9859a943..34b047e6d 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1364,15 +1364,32 @@ The ledger records the lowercase SHA-256 hex digest of that string. ### 20.3 Bounds -Canonicalization is bounded to **64 levels of nesting**, **1,048,576 entries per -collection** and **33,554,432 approximate cost units**. These exist only so a -hostile or runaway payload cannot pin a replica inside canonicalization; every -ordinary op has to pass, because the digest is computed on every apply and not -only on a reuse comparison. The first pair of bounds (4,096 entries / 262,144 -units) was tight enough to reject real edits: `clear` and `reset_doc` enumerate -every node id in `removed_nodes`, a `delete_node` on a hub node enumerates every -incident link, and a prompt value — or the `old` value an op captures — runs -past 256K characters routinely. +Canonicalization is bounded to **64 levels of nesting**, **4,096 entries per +collection** and **262,144 approximate cost units**. These are not chosen here: +they are mirrored exactly from `comfy-multi-player`'s `src/limits.ts` at +`221b2b2e470c79afaface24b1edcb53cdafc8922` (`MAX_PAYLOAD_DEPTH`, +`MAX_COLLECTION_ENTRIES`, `MAX_OP_COST`), cited by SHA rather than by branch. + +They exist only so a hostile or runaway payload cannot pin a replica inside +canonicalization, and every ordinary op has to pass. "The digest is computed on +every apply, not only on a reuse comparison" is true of **both** sides — CMP's +A8 canonicalizer charges the whole envelope in `applyOps` before its dedupe gate +— so a looser bound on one side rescues no edit. It only moves where an +oversized op fails, from a local `malformed_op` to a `malformed_op` from the +shared package after this side already accepted the payload. A comfy-cli-only +budget was briefly carried here (1,048,576 / 33,554,432) and is withdrawn as +exactly the cross-implementation validation drift one shared op package exists +to prevent. If a real edit needs more room, widen it in `comfy-multi-player` and +move this pin. + +Measured headroom at the shared values: the widest op this vocabulary mints from +a real workflow fixture is ~1.6K cost units over 13 entries, under 1% of the +budget. The three edits previously said to need a looser bound bind only well +past anything observed — `clear`/`reset_doc` at more than 4,096 nodes in one +document, a hub `delete_node` at more than 4,096 incident links on one node, and +a widget string at 131,064 characters when the op also captures an equal-sized +`old` (262,133 without one). The largest workflow in the comfy-cli fixtures has +11 nodes. The asymmetric case is the one to keep in mind: `{value: 25}` followed by the same `op_id` carrying `{value: 30}` rejects, while the same payload with its keys diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 01513af9f..b982740a7 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -163,16 +163,60 @@ def test_a_lone_surrogate_digests_instead_of_dying_on_the_utf8_encode(): assert len(ops._op_digest(op)) == 64 +def test_the_bounds_mirror_the_shared_op_package_values(): + """These are MIRRORED from the shared op package, not chosen here. + + ``comfy-multi-player``'s ``src/limits.ts`` at + ``221b2b2e470c79afaface24b1edcb53cdafc8922`` fixes ``MAX_PAYLOAD_DEPTH`` at + 64, ``MAX_COLLECTION_ENTRIES`` at 4096 and ``MAX_OP_COST`` at 262144, and + its A8 canonicalizer charges the whole envelope on EVERY apply, before the + dedupe gate (``applyOps`` -> ``opDigest`` -> ``canonicalJson`` -> + ``opBoundsRefusal``). So a looser bound here cannot rescue an oversized + edit; it only lets comfy-cli accept a payload the shared package then + refuses as ``malformed_op``. Widen it there and move this pin — never here + alone. + """ + assert ops._MAX_OP_PAYLOAD_DEPTH == 64 + assert ops._MAX_OP_COLLECTION_ENTRIES == 4096 + assert ops._MAX_OP_COST == 262_144 + + def test_ordinary_large_payloads_are_not_rejected_by_the_canonicalization_bounds(): - """The bounds exist to stop a runaway payload, not to cap a real edit. The - first pair (4,096 entries / 262,144 cost units) rejected edits that used to - succeed: ``clear``/``reset_doc`` enumerate every node id, ``delete_node`` - on a hub node enumerates every incident link, and a prompt value runs past - 256K characters. + """The bounds exist to stop a runaway payload, not to cap a real edit, and + at the shared values they still clear every real edit by two orders of + magnitude. The widest op the frozen vocabulary mints from an actual + workflow fixture in this repo measures ~1.6K cost units and 13 entries. + + The three edits cited as needing a looser bound are exercised here at sizes + far past anything observed: a ``clear`` enumerating a thousand node ids, a + hub ``delete_node`` enumerating a thousand incident links, and a 60K-char + prompt value whose op also captures an equal-sized ``old``. + """ + assert len(ops._op_digest({"op": "clear", "removed_nodes": list(range(1_000))})) == 64 + assert len(ops._op_digest({"op": "delete_node", "node_id": 7, "removed_links": list(range(1_000))})) == 64 + assert len(ops._op_digest({"op": "set_widget", "value": "x" * 60_000, "old": "y" * 60_000})) == 64 + + +def test_the_shared_bounds_bind_only_past_any_observed_workflow(): + """Where the mirrored bounds actually bite, pinned so the next reader does + not have to re-derive it before deciding whether an edit is really capped. + + ``removed_nodes``/``removed_links`` are flat lists, so the ENTRY cap is what + binds them, at 4,097 — a workflow with more than 4,096 nodes, or a single + node carrying more than 4,096 incident links. The largest workflow in this + repo's fixtures has 11 nodes. A widget string is charged by length, so the + COST budget binds it, and an op that captures an equal-sized ``old`` halves + the headroom: 131,064 characters for the bare value/old pair, a little less + once the envelope's own fields are charged. That is a 128 KiB string in one + widget. """ - assert len(ops._op_digest({"removed_nodes": list(range(20_000))})) == 64 - assert len(ops._op_digest({"removed_links": [[i, 1, 0, 2, 0, "T"] for i in range(10_000)]})) == 64 - assert len(ops._op_digest({"value": "x" * 1_000_000})) == 64 + assert len(ops._op_digest({"removed_nodes": [0] * ops._MAX_OP_COLLECTION_ENTRIES})) == 64 + with pytest.raises(ValueError, match="^malformed_op: array exceeds"): + ops._op_digest({"removed_nodes": [0] * (ops._MAX_OP_COLLECTION_ENTRIES + 1)}) + + assert len(ops._op_digest({"value": "x" * 131_064, "old": "y" * 131_064})) == 64 + with pytest.raises(ValueError, match="cost budget$"): + ops._op_digest({"value": "x" * 131_065, "old": "y" * 131_065}) def test_canonicalization_still_refuses_a_runaway_payload(): @@ -183,8 +227,10 @@ def test_canonicalization_still_refuses_a_runaway_payload(): ops._op_digest({"v": nested}) with pytest.raises(ValueError, match="^malformed_op: array exceeds"): ops._op_digest({"v": [0] * (ops._MAX_OP_COLLECTION_ENTRIES + 1)}) + # Cost-only overflow: 64 entries is well inside the entry cap, so this + # reaches the cost branch rather than tripping the entry branch first. with pytest.raises(ValueError, match="cost budget$"): - ops._op_digest({"v": ["x" * 4096] * 16_384}) + ops._op_digest({"v": ["x" * 4096] * 64}) with pytest.raises(ValueError, match="^malformed_op: op payload is not canonical JSON:"): ops._op_digest({"v": object()}) From ab5c33f0bd4530de07fff5b0f293dc64da8fc511 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 02:55:43 +0000 Subject: [PATCH 12/30] fix(workflow): bound a batch at 1,024 ops, the limit the shared applier enforces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `comfy-multi-player`'s `src/limits.ts` has four bounds on untrusted ops. Three of them — payload depth, collection entries, cost — are mirrored here. The fourth, `MAX_OPS_PER_BATCH` (1024 at 221b2b2e470c79afaface24b1edcb53cdafc8922), had no counterpart at all, so `workflow_ops` built and handed out a batch of any length. That is the same mint-then-refuse divergence the three payload bounds exist to close, one level up. `applyOps` checks the batch length before any op is processed and rejects every op in an over-long batch as `malformed_op`, and `inspectOps` raises the same code from the storage preflight — the batch is refused WHOLE, never truncated and never partially applied. So without a local bound the refusal arrives only after `comfy workflow apply` has already written the document, or after `templates fetch --emit-ops` has already told a caller the batch is the legal translation of its graph. Two enforcement points, with two different refusals, because the callers differ: * `apply_specs` raises `malformed_op: batch of ops exceeds the 1024-op limit; rejected before any op was processed`, checked on entry — ahead of the `at` coercion and the position planner, both of which are per-spec work, so the message's promise is literally true and the caller's document is untouched. * `replace_ops` raises `NotExpressibleError`, the existing "there is no legal batch for this graph" signal, rather than a bare `ValueError`. Both production callers already catch exactly that: `templates fetch --emit-ops` reports `ops_skipped` beside the workflow file it still writes, and `generate`'s emit path raises `EmitError`. A bare `ValueError` would escape both and crash a fetch that had otherwise succeeded. The count binds on the sum of `old` and `new`, since a replacement emits a `delete_node` per node already in `old`. No real workflow is affected, measured rather than assumed. Across all 735 workflows in `Comfy-Org/workflow_templates` — the gallery `templates fetch --emit-ops` reads — the longest batch `replace_ops` actually mints is 50 ops, 4.9% of the bound; 447 of those templates carry a subgraph definition, a canvas group or a reroute point and are refused as inexpressible before size is considered, and across all 735 nodes+links peaks at 212, so even if every one of them became expressible the worst case stays a fifth of the bound. Instrumenting the 1,820 existing tests that import `workflow_ops` shows the widest batch any of them builds is 19 specs through `apply_specs` and 7 ops through `replace_ops`, and none of them asserted the absence of a cap. The bound is mirrored, not chosen here, and cited by SHA rather than by branch. If a real edit ever needs a longer batch, widen it in `comfy-multi-player` and move the pin; never widen it here alone. `tests/comfy_cli/test_max_ops_per_batch.py` is new: it pins the constant to the shared value at that SHA, exercises both boundaries (1,024 applies/mints, 1,025 refuses at each surface), pins that the `old` document counts toward the batch, pins the fixture end of the headroom measurement, and pins the one document-sized payload this bound deliberately does not cover — a standalone `clear`/`reset_doc`, which enumerates node ids inside one op and is bounded by the 4,096-entry collection cap instead. The two refusal cases are red on the parent with `DID NOT RAISE`. `op-vocabulary-v1.md` gains amendment v1.12. --- CHANGELOG.md | 8 + comfy_cli/workflow_ops.py | 55 +++++- docs/op-vocabulary-v1.md | 56 ++++++ tests/comfy_cli/test_max_ops_per_batch.py | 173 +++++++++++++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 9 +- 5 files changed, 297 insertions(+), 4 deletions(-) create mode 100644 tests/comfy_cli/test_max_ops_per_batch.py diff --git a/CHANGELOG.md b/CHANGELOG.md index d1a887d29..6a5ecb588 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -186,6 +186,14 @@ history. ### Changed +- A structured-edit batch is bounded at 1,024 ops, the limit the shared + `comfy-multi-player` applier already enforces. `comfy workflow apply` refuses + a longer batch before any spec is processed and writes nothing, and + `templates fetch --emit-ops` reports `ops_skipped` beside the workflow file it + still writes rather than emitting a batch that would be rejected whole on + arrival. Measured over the whole template gallery, the longest batch this path + actually produces is 50 ops, so no real workflow is affected. + - Once every model byte is in, the progress line of `comfy deploy up`, `comfy deploy status` (with or without `--watch`) and a watching `comfy deploy promote` or `rollback` adds "finishing: putting the models in diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 80ae9880c..8e8613292 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -95,6 +95,21 @@ _MAX_OP_COLLECTION_ENTRIES = 4096 _MAX_OP_COST = 262_144 +# The fourth bound in that same `src/limits.ts` block (`MAX_OPS_PER_BATCH`, also +# 1024 at 221b2b2e470c79afaface24b1edcb53cdafc8922), and the only one that is +# about the BATCH rather than about one op's payload. CMP checks it in `applyOps` +# before any op is processed (`applier.ts`, `batch of N ops exceeds the 1024-op +# limit; rejected before any op was processed`) and again in `inspectOps`, so a +# longer batch is refused WHOLE — not truncated, and not partially applied. +# +# Without a counterpart here, comfy-cli happily builds and hands out a batch of +# any length, and the refusal lands on the shared package after comfy-cli has +# already written the document (`apply_specs`) or already told a caller the batch +# is the legal translation of its graph (`replace_ops`). That is the same +# mint-then-refuse shape the three payload bounds above exist to close, one level +# up. Mirror it, never widen it here alone. +_MAX_OPS_PER_BATCH = 1024 + #: Any surrogate code point in a Python ``str`` is a LONE surrogate — astral #: characters are single code points there — so matching the whole block is #: enough to find the ones that cannot be UTF-8 encoded. @@ -2655,13 +2670,20 @@ def reset_doc(workflow: dict, *, actor: str = "cli", base_version: int = 0) -> t class NotExpressibleError(ValueError): - """A graph uses structure the frozen v1 vocabulary cannot express. + """A graph the frozen v1 vocabulary cannot express as one op batch. Raised by :func:`replace_ops` INSTEAD of returning a partial batch. A partial batch is the dangerous answer: it applies cleanly and leaves a document that is not the graph the caller asked for. The caller is expected to fall back to whatever whole-document path it had before (the cloud agent re-mints), and to say why. + + Two reasons reach it. The graph may use STRUCTURE no frozen op kind can + create (a subgraph definition, a canvas group, a reroute point). Or the + translation may simply be too LONG — more than ``_MAX_OPS_PER_BATCH`` ops, + which the shared applier refuses whole. Both are "there is no legal batch + for this graph", and both want the same caller behaviour, so they share the + type rather than making every caller learn a second one. """ @@ -2760,7 +2782,8 @@ def replace_ops(old: dict, new: dict, *, actor: str = "cli", base_version: int = it reproduces the STRUCTURE (classes + wiring) while the op path reproduces the graph exactly, widget values included. - :raises NotExpressibleError: ``new`` uses structure no frozen op can create. + :raises NotExpressibleError: ``new`` uses structure no frozen op can create, + or its translation needs more than ``_MAX_OPS_PER_BATCH`` ops. """ reason = _inexpressible_reason(new) if reason: @@ -2848,6 +2871,17 @@ def replace_ops(old: dict, new: dict, *, actor: str = "cli", base_version: int = }, ) ) + # The batch is counted at the end rather than predicted up front because the + # exact length is only known here (a link to a node `new` does not contain is + # dropped above, so it costs no op), and nothing has left the function yet — + # the ops exist only in this local list. Returning a longer batch would hand + # the caller an artifact the shared applier rejects whole as `malformed_op`, + # which is the same "it applies cleanly nowhere" answer a partial batch is. + if len(ops) > _MAX_OPS_PER_BATCH: + raise NotExpressibleError( + f"the workflow needs {len(ops)} ops, more than the {_MAX_OPS_PER_BATCH}-op batch limit " + "(delete_node per existing node, add_node per node, connect per link)" + ) return ops @@ -3363,7 +3397,22 @@ def _split_ref_slot(spec_val: str, aliases: dict[str, Any]) -> tuple[Any, Any]: def apply_specs( workflow: dict, graph, specs: list, *, actor: str = "cli", base_version: int = 0 ) -> tuple[dict, list, dict]: - """Apply edit specs to ``workflow`` in order. Returns (workflow, ops, aliases).""" + """Apply edit specs to ``workflow`` in order. Returns (workflow, ops, aliases). + + :raises ValueError: the batch is longer than ``_MAX_OPS_PER_BATCH``. + """ + # FIRST, before the `at` coercion and before `layout.assign_positions` — both + # of which are per-spec work — so the refusal really is "before any op was + # processed" the way the shared package's is. This is the batch counterpart + # of the three payload bounds: `applyOps` refuses an over-long batch WHOLE, + # so accepting it here applies the edit locally and has every op in it + # rejected downstream. §4's abort-remainder contract has nothing to say about + # that case — it describes which ops in a batch apply, and here none do. + if len(specs) > _MAX_OPS_PER_BATCH: + raise ValueError( + f"malformed_op: batch of {len(specs)} ops exceeds the {_MAX_OPS_PER_BATCH}-op limit; " + "rejected before any op was processed" + ) # Parse a string `at` up front: layout treats a pinned `at` as an obstacle # and reads it as coordinates. specs = [ diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 34b047e6d..d0c54a174 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1400,3 +1400,59 @@ in a different insertion order is an ordinary no-op. bullet now cites this section. Downstream repos pinning this document by SHA move the SHA together with their comfy-cli pin, and must move their CMP A8 pin with it. + +## 21. Amendment v1.12 — 2026-10-31 (a batch is bounded at 1,024 ops) + +**A batch carries at most 1,024 ops.** `comfy-multi-player`'s `src/limits.ts` at +`221b2b2e470c79afaface24b1edcb53cdafc8922` fixes `MAX_OPS_PER_BATCH` at 1024 and +refuses a longer batch **whole** — `applyOps` checks it before any op is +processed and returns a `malformed_op` rejection for every op in the batch, and +`inspectOps` raises `malformed_op` from the storage preflight. comfy-cli had no +counterpart, so `apply_specs` would accept and apply a batch of any length and +`replace_ops` would hand a caller one, and the refusal arrived from the shared +package only after this side had committed to the write. + +That is the same mint-then-refuse divergence v1.11 §20.3 closed for the three +payload bounds, one level up: §4's abort-remainder contract is about which ops in +a batch apply, and an over-long batch has no answer under it at all because none +of them do. The bound is therefore mirrored, not chosen here, and cited by SHA +rather than by branch for the same reason §20.3 gives. If a real edit needs a +longer batch, widen it in `comfy-multi-player` and move this pin; never widen it +here alone. + +Where it is enforced, and the two different refusals: + +* **`apply_specs`** raises `malformed_op: batch of ops exceeds the 1024-op + limit; rejected before any op was processed`, checked on entry — before the + `at` coercion and before the position planner, both of which are per-spec + work, so the message's promise is literally true. +* **`replace_ops`** raises **`NotExpressibleError`**, the existing "there is no + legal batch for this graph" signal, rather than a bare `ValueError`. Its two + reasons are now *structure no frozen kind can create* and *a translation + longer than the bound*; both want the same caller behaviour, which both + production callers already implement — `templates fetch --emit-ops` reports + `ops_skipped` beside the file it still wrote, and `generate`'s emit path + raises `EmitError`. The count binds on the SUM of `old` and `new`, because + §8.8's replacement shape emits a `delete_node` per node already in `old` + before the adds. + +Measured headroom. Across all 735 workflows in `Comfy-Org/workflow_templates` — +the gallery `templates fetch --emit-ops` reads — the longest batch `replace_ops` +actually mints is **50 ops**, 4.9% of the bound. 447 of those templates carry a +subgraph definition, a canvas group or a reroute point and are refused as +inexpressible before size is considered; across all 735, nodes+links peaks at +212, so even if every one of them became expressible the worst case stays a fifth +of the bound. The largest expressible workflow in comfy-cli's own fixtures mints +3 ops. + +The one document-sized payload this bound does **not** cover is a standalone +`clear` or `reset_doc`, which enumerates every node id inside ONE op rather than +as one op each. Those are bounded by §20.3's 4,096-entry collection cap instead, +and §1.5/§1.6 keep them out of `BATCHABLE_OPS`, so no large document turns into a +long batch behind a caller's back. + +**No change to §§1-3, 5-8.** No op kind was added, removed, or re-scoped; +`FROZEN_OPS` / `DEFERRED_OPS` / `BATCHABLE_OPS` are untouched. §4 gains an outer +precondition — a batch must be within the bound before abort-remainder has +anything to say about it — and is otherwise unaltered. Downstream repos pinning +this document by SHA move the SHA together with their comfy-cli pin. diff --git a/tests/comfy_cli/test_max_ops_per_batch.py b/tests/comfy_cli/test_max_ops_per_batch.py new file mode 100644 index 000000000..a20cd9190 --- /dev/null +++ b/tests/comfy_cli/test_max_ops_per_batch.py @@ -0,0 +1,173 @@ +"""A batch is bounded at ``_MAX_OPS_PER_BATCH``, mirrored from the shared package. + +``comfy-multi-player``'s ``src/limits.ts`` has FOUR bounds on untrusted ops. The +three payload ones (depth, collection entries, cost) are pinned in +``test_op_id_reuse_contract.py`` beside the canonicalizer they guard. This file +owns the fourth, which is about the BATCH rather than about one op's payload, and +is therefore enforced somewhere else entirely: at the two surfaces that build or +dispatch a whole batch, ``apply_specs`` and ``replace_ops``. + +Why a local bound at all, when the shared package already has one: without it +comfy-cli builds a batch of any length and the refusal lands downstream *after* +comfy-cli has already written the document or already handed a caller the batch +as the legal translation of its graph. That is the mint-then-refuse shape — the +producer commits, the shared applier rejects the whole batch — that the payload +bounds exist to close one level down. +""" + +from __future__ import annotations + +import json +from pathlib import Path +from typing import Any + +import pytest + +from comfy_cli import workflow_ops as ops +from comfy_cli.cql.engine import Graph + +_OBJECT_INFO: dict[str, Any] = { + "KSampler": { + "input": {"required": {"steps": ["INT", {"default": 20, "min": 1, "max": 10000}]}}, + "input_order": {"required": ["steps"]}, + "output": ["LATENT"], + "output_name": ["LATENT"], + "category": "sampling", + "display_name": "KSampler", + "python_module": "nodes", + }, +} + +_FIXTURES = Path(__file__).parent / "fixtures" + + +@pytest.fixture +def graph() -> Graph: + return Graph.from_object_info(_OBJECT_INFO) + + +def _nodes(count: int) -> dict: + """A frontend-format graph of ``count`` unlinked nodes. + + ``replace_ops`` mints one ``add_node`` per node and one ``connect`` per link, + so an unlinked graph makes the op count equal to the node count and the + boundary exact. + """ + return { + "nodes": [ + {"id": i + 1, "type": "KSampler", "widgets_values": [20], "inputs": [], "outputs": []} for i in range(count) + ], + "links": [], + } + + +def _add_node_specs(count: int) -> list[dict]: + return [{"op": "add_node", "class_type": "KSampler"} for _ in range(count)] + + +# --- the constant is mirrored, not chosen here ------------------------------ + + +def test_the_batch_bound_mirrors_the_shared_op_package_value(): + """``MAX_OPS_PER_BATCH`` is 1024 in ``comfy-multi-player``'s ``src/limits.ts`` + at ``221b2b2e470c79afaface24b1edcb53cdafc8922`` — cited by SHA rather than by + branch, because the whole point is that the two implementations agree. + + The shared package enforces it in two places, both of which refuse the batch + WHOLE rather than truncating or partially applying it: ``applyOps`` checks it + before any op is processed and returns a ``malformed_op`` rejection for every + op in the batch, and ``inspectOps`` raises ``malformed_op`` from the storage + preflight. So comfy-cli cannot buy anything by allowing a longer batch — it + can only move where the batch dies, to after comfy-cli has committed to it. + Widen it there and move this pin; never widen it here alone. + """ + assert ops._MAX_OPS_PER_BATCH == 1024 + + +# --- the boundary: N applies, N+1 is refused -------------------------------- + + +def test_apply_specs_accepts_a_batch_of_exactly_the_limit(graph): + workflow, minted, _aliases = ops.apply_specs({"nodes": [], "links": []}, graph, _add_node_specs(1024)) + assert len(minted) == ops._MAX_OPS_PER_BATCH + assert len(workflow["nodes"]) == ops._MAX_OPS_PER_BATCH + + +def test_apply_specs_refuses_one_op_past_the_limit(graph): + workflow = {"nodes": [], "links": []} + with pytest.raises(ValueError, match=r"^malformed_op: batch of 1025 ops exceeds the 1024-op limit"): + ops.apply_specs(workflow, graph, _add_node_specs(1025)) + # "Rejected before any op was processed", the same promise the shared + # package's message makes: the document the caller handed in is untouched, + # including by the position planner that runs on every spec. + assert workflow == {"nodes": [], "links": []} + + +def test_replace_ops_mints_a_batch_of_exactly_the_limit(): + assert len(ops.replace_ops({"nodes": [], "links": []}, _nodes(1024))) == ops._MAX_OPS_PER_BATCH + + +def test_replace_ops_refuses_to_mint_one_op_past_the_limit(): + """Refused as ``NotExpressibleError``, not as a bare ``ValueError``. + + That is what the two production callers already catch, and the distinction is + behavioural rather than cosmetic: ``templates fetch --emit-ops`` treats it as + non-fatal and reports ``ops_skipped`` beside a file it has still written, + while ``generate``'s emit path turns it into an ``EmitError``. A bare + ``ValueError`` would escape both and crash a fetch that had otherwise + succeeded. + """ + with pytest.raises(ops.NotExpressibleError, match=r"needs 1025 ops, more than the 1024-op batch limit"): + ops.replace_ops({"nodes": [], "links": []}, _nodes(1025)) + + +def test_the_old_document_counts_toward_the_batch_too(): + """``replace_ops`` emits a ``delete_node`` for every node already in ``old`` + before the adds, so the bound binds on the SUM. Counting only ``new`` would + let a 600-node replacement of a 600-node canvas mint 1,200 ops. + """ + assert len(ops.replace_ops(_nodes(512), _nodes(512))) == ops._MAX_OPS_PER_BATCH + with pytest.raises(ops.NotExpressibleError, match=r"needs 1200 ops"): + ops.replace_ops(_nodes(600), _nodes(600)) + + +# --- where it actually bites, measured rather than assumed ------------------ + + +def test_the_batch_bound_binds_only_far_past_any_real_workflow(): + """Pinned so the next reader does not have to re-derive the headroom before + deciding whether the bound caps a real edit. + + Measured over all 735 workflows in ``Comfy-Org/workflow_templates`` (the + gallery ``templates fetch --emit-ops`` reads), the longest batch + ``replace_ops`` actually mints is **50 ops** — 4.9% of the bound — from + ``templates-1_input-multiple_styles_prompt``. 447 of those templates carry a + subgraph definition, a canvas group or a reroute point, so ``replace_ops`` + refuses them as inexpressible before size is even considered; across all 735 + the absolute upper bound on nodes+links is 212, still a fifth of the bound. + The largest expressible workflow in this repo's own fixtures mints 3 ops. + + This test pins the fixture end of that measurement, which is the half that + can regress in CI. + """ + fixture = json.loads((_FIXTURES / "seedream_5_0_pro_t2i_ui.json").read_text(encoding="utf-8")) + minted = ops.replace_ops({"nodes": [], "links": []}, fixture) + assert len(minted) * 100 < ops._MAX_OPS_PER_BATCH, ( + f"the widest real fixture batch is {len(minted)} ops; if it is approaching " + f"{ops._MAX_OPS_PER_BATCH} the bound needs widening in comfy-multi-player first" + ) + + +def test_no_production_surface_builds_a_batch_near_the_bound(graph): + """The one shape in the frozen vocabulary that scales with document size and + is NOT capped by this bound: a standalone ``clear`` or ``reset_doc``, which + carries every node id inside ONE op's payload rather than as one op each. + Those are bounded by ``_MAX_OP_COLLECTION_ENTRIES`` (4,096 entries) instead, + and they are standalone-only — ``BATCHABLE_OPS`` excludes them — so there is + no shape where a large document turns into a long batch behind the caller's + back. + """ + assert "clear" not in ops.BATCHABLE_OPS + assert "reset_doc" not in ops.BATCHABLE_OPS + _workflow, op = ops.clear(_nodes(2048)) + assert len(op["removed_nodes"]) == 2048 diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index b982740a7..e469ce707 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -168,7 +168,8 @@ def test_the_bounds_mirror_the_shared_op_package_values(): ``comfy-multi-player``'s ``src/limits.ts`` at ``221b2b2e470c79afaface24b1edcb53cdafc8922`` fixes ``MAX_PAYLOAD_DEPTH`` at - 64, ``MAX_COLLECTION_ENTRIES`` at 4096 and ``MAX_OP_COST`` at 262144, and + 64, ``MAX_COLLECTION_ENTRIES`` at 4096, ``MAX_OP_COST`` at 262144 and + ``MAX_OPS_PER_BATCH`` at 1024, and its A8 canonicalizer charges the whole envelope on EVERY apply, before the dedupe gate (``applyOps`` -> ``opDigest`` -> ``canonicalJson`` -> ``opBoundsRefusal``). So a looser bound here cannot rescue an oversized @@ -179,6 +180,12 @@ def test_the_bounds_mirror_the_shared_op_package_values(): assert ops._MAX_OP_PAYLOAD_DEPTH == 64 assert ops._MAX_OP_COLLECTION_ENTRIES == 4096 assert ops._MAX_OP_COST == 262_144 + # The fourth bound in the same `src/limits.ts` block bounds the BATCH rather + # than one op's payload, so it is enforced at `apply_specs`/`replace_ops` + # instead of in the canonicalizer and is pinned, with its boundary cases, in + # `test_max_ops_per_batch.py`. Asserted here too so that reading this list + # cannot suggest only three of the four are mirrored. + assert ops._MAX_OPS_PER_BATCH == 1024 def test_ordinary_large_payloads_are_not_rejected_by_the_canonicalization_bounds(): From 1ff58bc82e39358b29f101745769f2e153a079a5 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:33:06 +0000 Subject: [PATCH 13/30] fix(workflow): count the ops a batch mints, not only its specs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `apply_specs` bounded `len(specs)`, and one spec is not one op. `set_dynamic_group_rows` expands into a row-count write plus one `set_widget` per row field, so a spec list comfortably inside the bound can still return a batch past it: 200 specs here mint 1,100 ops. The shared applier refuses an over-long batch WHOLE, so that batch applied locally, was handed to the caller, and had every op in it rejected downstream as `malformed_op` — exactly the mint-then-refuse shape the bound was added to close. The entry check stays, as the cheap half: a spec list already longer than the bound cannot mint a batch within it (every spec mints at least one op), and catching it there refuses ahead of the `at` coercion and the position planner. Its message now says `specs`, because that is what it counted. The half that binds is a `len(ops)` check after the loop, inside the `try`, so `_rehint_discarded_batch` records `spec_index` and `applied_count` the way every other mid-batch refusal does — and `applied_count` is 0, because the caller discards the whole batch. Addresses: - https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284384 (Medium, 6/6 reviewers) - https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430123078 (CodeRabbit) --- comfy_cli/workflow_ops.py | 36 +++++++++++---- docs/op-vocabulary-v1.md | 14 ++++-- tests/comfy_cli/test_max_ops_per_batch.py | 53 ++++++++++++++++++++++- 3 files changed, 89 insertions(+), 14 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 96455a3d4..4f2050db0 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3446,18 +3446,25 @@ def apply_specs( ) -> tuple[dict, list, dict]: """Apply edit specs to ``workflow`` in order. Returns (workflow, ops, aliases). - :raises ValueError: the batch is longer than ``_MAX_OPS_PER_BATCH``. + :raises ValueError: the batch mints more than ``_MAX_OPS_PER_BATCH`` ops. """ - # FIRST, before the `at` coercion and before `layout.assign_positions` — both - # of which are per-spec work — so the refusal really is "before any op was - # processed" the way the shared package's is. This is the batch counterpart - # of the three payload bounds: `applyOps` refuses an over-long batch WHOLE, - # so accepting it here applies the edit locally and has every op in it - # rejected downstream. §4's abort-remainder contract has nothing to say about - # that case — it describes which ops in a batch apply, and here none do. + # The bound is on the OPS, and one spec is not one op — `set_dynamic_group_rows` + # expands into a row-count write plus one `set_widget` per row field. So this + # entry check is the cheap half: a spec list already longer than the bound + # cannot mint a batch within it (every spec mints at least one op), and + # catching it here refuses before the `at` coercion and before + # `layout.assign_positions`, both of which are per-spec work. The half that + # actually binds is the `len(ops)` check after the loop below; a batch of + # 1,000 specs that expands past 1,024 ops passes this one and is caught there. + # + # Either way the refusal is whole-batch, because `applyOps` refuses an + # over-long batch WHOLE: accepting it here applies the edit locally and has + # every op in it rejected downstream. §4's abort-remainder contract has + # nothing to say about that case — it describes which ops in a batch apply, + # and here none do. if len(specs) > _MAX_OPS_PER_BATCH: raise ValueError( - f"malformed_op: batch of {len(specs)} ops exceeds the {_MAX_OPS_PER_BATCH}-op limit; " + f"malformed_op: batch of {len(specs)} specs exceeds the {_MAX_OPS_PER_BATCH}-op limit; " "rejected before any op was processed" ) # Parse a string `at` up front: layout treats a pinned `at` as an obstacle @@ -3610,6 +3617,17 @@ def unknown_size(class_type: Any) -> list[float] | None: ) input_targets.add(encoded_target) ops.append(op) + # The entry check above counted specs. This one counts what they + # actually minted, which is what `applyOps` bounds: a batch of 1,000 + # specs carrying a few `set_dynamic_group_rows` clears the entry check + # and still returns more than 1,024 ops, and the shared applier then + # refuses every one of them as `malformed_op` after comfy-cli has + # already written the document. Inside the `try` so the discard rehint + # below records `spec_index`/`applied_count` like every other refusal + # in this batch, and `applied_count` is 0 — the caller discards the + # whole batch, so nothing this loop wrote survives. + if len(ops) > _MAX_OPS_PER_BATCH: + raise ValueError(f"malformed_op: batch mints {len(ops)} ops, more than the {_MAX_OPS_PER_BATCH}-op limit") except (NotBatchableError, DeprecatedNodeType): # Already carries a registered code and a hint that says what to do # instead — don't wrap it into a generic hint. diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index d0c54a174..0069f04a7 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1422,10 +1422,16 @@ here alone. Where it is enforced, and the two different refusals: -* **`apply_specs`** raises `malformed_op: batch of ops exceeds the 1024-op - limit; rejected before any op was processed`, checked on entry — before the - `at` coercion and before the position planner, both of which are per-spec - work, so the message's promise is literally true. +* **`apply_specs`** checks it TWICE, because one spec is not one op. On entry + it raises `malformed_op: batch of specs exceeds the 1024-op limit; + rejected before any op was processed` — before the `at` coercion and before + the position planner, both of which are per-spec work, so the message's + promise is literally true. That check cannot be the whole bound: + `set_dynamic_group_rows` expands into a row-count write plus one `set_widget` + per row field, so a spec list within the bound can still mint a batch + past it. After the loop, and still inside the batch's discard handler, it + raises `malformed_op: batch mints ops, more than the 1024-op limit`; + `applied_count` is 0 there like every other mid-batch refusal. * **`replace_ops`** raises **`NotExpressibleError`**, the existing "there is no legal batch for this graph" signal, rather than a bare `ValueError`. Its two reasons are now *structure no frozen kind can create* and *a translation diff --git a/tests/comfy_cli/test_max_ops_per_batch.py b/tests/comfy_cli/test_max_ops_per_batch.py index a20cd9190..fe8e3b5c0 100644 --- a/tests/comfy_cli/test_max_ops_per_batch.py +++ b/tests/comfy_cli/test_max_ops_per_batch.py @@ -17,6 +17,7 @@ from __future__ import annotations +import copy import json from pathlib import Path from typing import Any @@ -65,6 +66,31 @@ def _add_node_specs(count: int) -> list[dict]: return [{"op": "add_node", "class_type": "KSampler"} for _ in range(count)] +_DYNAMIC_GROUP_FIXTURE = json.loads((_FIXTURES / "dynamic_group.json").read_text(encoding="utf-8")) + + +@pytest.fixture +def graph_with_group() -> Graph: + """A catalog carrying a DynamicGroup class, so a batch can be built whose op + count is larger than its spec count.""" + return Graph.from_object_info(copy.deepcopy(_DYNAMIC_GROUP_FIXTURE["object_info"])) + + +def _group_specs(pairs: int) -> list[dict]: + """``pairs`` × (one ``add_node``, one three-row ``set_dynamic_group_rows``). + + Each pair is 2 specs and 11 ops — 1 for the node, then the row count plus + three row fields (``lora_name``, ``strength``, ``enabled``) × 3 rows. A + group may only be written once per batch, hence one fresh node per write. + """ + rows = [{"lora_name": "A.safetensors", "strength": 1.0} for _ in range(3)] + specs: list[dict] = [] + for i in range(pairs): + specs.append({"op": "add_node", "class_type": "DevToolsNodeWithDynamicGroup", "as": f"n{i}"}) + specs.append({"op": "set_dynamic_group_rows", "node": f"$n{i}", "group": "loras", "rows": rows}) + return specs + + # --- the constant is mirrored, not chosen here ------------------------------ @@ -95,7 +121,7 @@ def test_apply_specs_accepts_a_batch_of_exactly_the_limit(graph): def test_apply_specs_refuses_one_op_past_the_limit(graph): workflow = {"nodes": [], "links": []} - with pytest.raises(ValueError, match=r"^malformed_op: batch of 1025 ops exceeds the 1024-op limit"): + with pytest.raises(ValueError, match=r"^malformed_op: batch of 1025 specs exceeds the 1024-op limit"): ops.apply_specs(workflow, graph, _add_node_specs(1025)) # "Rejected before any op was processed", the same promise the shared # package's message makes: the document the caller handed in is untouched, @@ -103,6 +129,31 @@ def test_apply_specs_refuses_one_op_past_the_limit(graph): assert workflow == {"nodes": [], "links": []} +def test_apply_specs_counts_the_ops_the_specs_expand_into_not_the_specs(graph_with_group): + """One spec is not one op, so the entry check on ``len(specs)`` is only the + cheap half of the bound. + + ``set_dynamic_group_rows`` expands into a row-count write plus one + ``set_widget`` per row field, so 200 specs here mint 1,100 ops: comfortably + past the entry check and comfortably past the bound. Without the second + check this batch applies locally and is handed to a caller, and ``applyOps`` + then refuses every op in it as ``malformed_op`` — the mint-then-refuse shape + this bound exists to close. Red on the parent, which returns 1,100 ops. + """ + with pytest.raises(ValueError, match=r"^malformed_op: batch mints 1100 ops, more than the 1024-op limit") as exc: + ops.apply_specs({"nodes": [], "links": []}, graph_with_group, _group_specs(100)) + # Refused like every other mid-batch failure, so a summary-receipt caller + # reads the same structured position and the same "nothing was written". + assert exc.value.applied_count == 0 + + +def test_a_batch_whose_expansion_stays_within_the_bound_still_applies(graph_with_group): + """The complement of the test above: the second check bounds the expansion, + it does not refuse an expanding batch as such.""" + _workflow, minted, _aliases = ops.apply_specs({"nodes": [], "links": []}, graph_with_group, _group_specs(90)) + assert len(minted) == 990 + + def test_replace_ops_mints_a_batch_of_exactly_the_limit(): assert len(ops.replace_ops({"nodes": [], "links": []}, _nodes(1024))) == ops._MAX_OPS_PER_BATCH From 5329275012a1c17c0360991ce0bd533ff29e59c3 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:35:32 +0000 Subject: [PATCH 14/30] fix(workflow): spell an integer past 2^53 the way ECMAScript spells it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `_canonical_value` rendered every `int` with `str`, which is exact at any magnitude. The counterpart has no such type: JSON carries no integer, `JSON.parse` reads every numeric literal as an IEEE-754 double, and CMP's canonicalizer refuses a `BigInt` payload outright (`applier.ts`: `rejectBigIntPayload`). Past 2^53 the other side therefore holds the ROUNDED value and `Number::toString` spells that. So this was the failure the float rule exists to prevent, one type over. A seed at an INT widget's `0xffffffffffffffff` maximum spelled `18446744073709551615` here and `18446744073709552000` after a relay through JS, and `10**21` spelled `1e+21` there — an identical op echoed back through the shared package digested differently and was refused as `op_id_reuse`. Inside the exact range nothing changes, and that is every integer a widget, node id, link id or stamp carries. Outside it the value goes through the same double path as a float; past the double range `JSON.parse` yields Infinity, which `JSON.stringify` renders as `null`. An integer object KEY is the one divergence, because a property name is coerced with `String()` rather than rendered by `JSON.stringify` — `"Infinity"` there, not `null` — so the int branch of `_canonical_key` falls through to the float path instead of duplicating it. The cost charge stays a flat 8 units: `src/limits.ts` documents the model as "8 per numeric/leaf", so charging a huge integer by its digit count would refuse a payload CMP accepts. Expected spellings in the new tests come from a real engine, not from the spec text. `op-vocabulary-v1.md` gains amendment v1.13; CMP needs no change, since `JSON.stringify` already produces these. Addresses: - https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284387 (Medium, 5/6 reviewers) - https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430123060 (CodeRabbit) --- comfy_cli/workflow_ops.py | 50 +++++++++++++++++- docs/op-vocabulary-v1.md | 42 ++++++++++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 53 ++++++++++++++++++++ 3 files changed, 143 insertions(+), 2 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 4f2050db0..2200487a3 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -161,6 +161,39 @@ def _es_number(value: float) -> str: return f"{mantissa}e{'+' if e >= 0 else '-'}{abs(e)}" +#: ECMAScript holds an integer exactly only up to here. JSON has no integer type +#: on the other side of the wire — `JSON.parse` reads every numeric literal as an +#: IEEE-754 double, and comfy-multi-player's canonicalizer refuses a `BigInt` +#: payload outright (`applier.ts`: `rejectBigIntPayload`) — so past this bound the +#: value ARRIVES there rounded and `Number::toString` spells the rounded number. +_ES_EXACT_INT = 2**53 + + +def _es_int(value: int) -> str: + """Render one ``int`` as ECMAScript renders the number ``JSON.parse`` makes + of the same literal. + + Inside ``_ES_EXACT_INT`` the two spellings already agree, so the exact digits + are kept. Outside it they do not, and the disagreement is not cosmetic: a + seed at a FLOAT/INT widget's ``0xffffffffffffffff`` maximum renders + ``18446744073709551615`` here and ``18446744073709552000`` after a relay + through JS, and ``10**21`` renders as ``1e+21`` there — so an IDENTICAL op + echoed back through the shared package digests differently and is refused as + ``op_id_reuse``. That is the failure :func:`_es_number` exists to prevent, + one type over, which is why the rendering goes through the same double path. + """ + if -_ES_EXACT_INT <= value <= _ES_EXACT_INT: + return str(value) + try: + as_double = float(value) + except OverflowError: + # Past the double range `JSON.parse` yields Infinity, which + # `JSON.stringify` renders as `null` — the same spelling the non-finite + # float branch below uses. + return "null" + return _es_number(as_double) + + def _canonical_string(value: str) -> str: """One JSON string literal, escaped the way ``JSON.stringify`` escapes it. @@ -186,7 +219,17 @@ def _canonical_key(key: Any) -> str: if isinstance(key, bool): # before int: bool is an int subclass return "true" if key else "false" if isinstance(key, int): - return str(key) + if -_ES_EXACT_INT <= key <= _ES_EXACT_INT: + return str(key) + # Past the exact range the property name is coerced from the DOUBLE + # `JSON.parse` produced, so fall through to the float path below rather + # than spelling out digits no JS object key would ever carry. Note the + # Infinity spelling there, not `_es_int`'s `null`: a KEY is coerced with + # `String()`, not rendered by `JSON.stringify`. + try: + key = float(key) + except OverflowError: + key = math.inf if key > 0 else -math.inf if isinstance(key, float): if math.isnan(key): return "NaN" @@ -209,8 +252,11 @@ def _canonical_value(value: Any, depth: int, budget: list[int]) -> str: budget[0] += 8 rendered = "true" if value else "false" elif isinstance(value, int): + # Still a flat 8, deliberately: the cost model is mirrored from the + # shared package ("8 per numeric/leaf", `src/limits.ts`), so charging a + # huge int by its digit count would refuse a payload CMP accepts. budget[0] += 8 - rendered = str(value) + rendered = _es_int(value) elif isinstance(value, float): budget[0] += 8 # ``JSON.stringify`` renders every non-finite number as ``null``, so diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 0069f04a7..93eed71ef 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1462,3 +1462,45 @@ long batch behind a caller's back. precondition — a batch must be within the bound before abort-remainder has anything to say about it — and is otherwise unaltered. Downstream repos pinning this document by SHA move the SHA together with their comfy-cli pin. + +## 22. Amendment v1.13 — 2026-10-31 (an integer past 2^53 is spelled as the double it becomes) + +**§20.1's "numbers rendered as ECMAScript renders them" covers integers too, and +comfy-cli did not implement it that way.** It rendered every `int` with Python's +`str`, which is exact at any magnitude. The counterpart has no such type: JSON +carries no integer, `JSON.parse` reads every numeric literal as an IEEE-754 +double, and CMP's canonicalizer refuses a `BigInt` payload outright +(`applier.ts`: `rejectBigIntPayload`). So past 2^53 the other side holds the +ROUNDED value and `Number::toString` spells that. + +The consequence was the failure §20.1's float rule exists to prevent, one type +over. A seed at an INT widget's `0xffffffffffffffff` maximum spelled +`18446744073709551615` here and `18446744073709552000` after a relay through JS, +and `10**21` spelled `1e+21` there — so an **identical** op echoed back through +the shared package digested differently and was refused as `op_id_reuse`. + +The rule, which changes nothing inside the exact range: + +* `-2^53 <= n <= 2^53` keeps its exact digits — the two spellings already agree + there, and this is every integer any widget, node id, link id or stamp + carries; +* outside it, the value is rendered through the same double path as a float, so + it reads as `JSON.stringify(JSON.parse(literal))` would; +* past the double range entirely (`10**400`), `JSON.parse` yields `Infinity` and + `JSON.stringify` renders `null`, matching §20.1's non-finite bullet; +* an integer **object key** is the one place the two diverge, because a property + name is coerced with `String()` rather than rendered by `JSON.stringify`: + there the non-finite end is `"Infinity"` / `"-Infinity"`. Only a + programmatically built op can reach a non-`str` key at all — parsed JSON + always has string keys. + +The **cost charge is unchanged** at a flat 8 units per number, deliberately: +`src/limits.ts` documents the model as "8 per numeric/leaf", so charging a huge +integer by its digit count would refuse a payload CMP accepts — the same +validation drift §20.3 withdrew a comfy-cli-only budget to avoid. + +**No change to §§1-8, and no change needed in `comfy-multi-player`.** CMP +already produces these spellings, because it canonicalizes with +`JSON.stringify`; this amendment records that comfy-cli now agrees with it. Its +only behavioural effect is on an op carrying an integer past 2^53, which now +digests as its JS spelling. diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index e469ce707..35ada6713 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -110,6 +110,59 @@ def test_numbers_are_rendered_the_way_ecmascript_renders_them(): assert ops._canonical_op({"v": 5e-324}) == '{"v":5e-324}' +def test_an_integer_past_the_exact_range_is_spelled_the_way_js_spells_it(): + """``JSON.parse`` has no integer type: it reads every numeric literal as an + IEEE-754 double, and CMP's canonicalizer refuses a ``BigInt`` payload + outright (``applier.ts``: ``rejectBigIntPayload``). So past 2**53 the other + side holds the ROUNDED value and ``Number::toString`` spells that, while + ``str(value)`` here would spell the exact digits. + + These are the spellings ``JSON.stringify(JSON.parse(literal))`` produces, + taken from a real engine, not from the spec text. + """ + assert ops._canonical_op({"v": 2**53}) == '{"v":9007199254740992}' + assert ops._canonical_op({"v": 2**53 + 1}) == '{"v":9007199254740992}' + # A legal INT-widget maximum: a seed at 0xffffffffffffffff. + assert ops._canonical_op({"v": 18446744073709551615}) == '{"v":18446744073709552000}' + assert ops._canonical_op({"v": -18446744073709551615}) == '{"v":-18446744073709552000}' + # At 1e21 JS switches to exponent form for an integer too. + assert ops._canonical_op({"v": 10**21}) == '{"v":1e+21}' + assert ops._canonical_op({"v": 10**20}) == '{"v":100000000000000000000}' + # Past the double range `JSON.parse` yields Infinity, which stringifies as + # `null` — the same spelling the non-finite float branch uses. + assert ops._canonical_op({"v": 10**400}) == '{"v":null}' + # Inside the exact range nothing changed: the digits are kept. + assert ops._canonical_op({"v": 20}) == '{"v":20}' + assert ops._canonical_op({"v": -(2**53)}) == '{"v":-9007199254740992}' + + +def test_a_max_seed_relayed_through_js_digests_the_same(graph): + """The failure the test above prevents, end to end. Without the rounding an + op carrying ``0xffffffffffffffff`` digests one way here and another after a + JS relay, so the IDENTICAL op echoed back is refused as ``op_id_reuse`` — + exactly what the float spelling was fixed to stop. + """ + workflow = _workflow() + exact = _op(18446744073709551615) + ops.apply_op(workflow, exact, graph) + relayed = _op(18446744073709552000) # what `JSON.parse(JSON.stringify(op))` yields + assert ops._op_digest(relayed) == ops._op_digest(exact) + assert ops.apply_op(workflow, relayed, graph) is workflow + + +def test_an_integer_object_key_past_the_exact_range_coerces_like_a_js_key(): + """A key is coerced with ``String()``, not rendered by ``JSON.stringify``, so + the two differ on the non-finite end: ``String(Infinity)`` is ``"Infinity"`` + where ``JSON.stringify(Infinity)`` is ``null``. Only a programmatically built + op reaches a non-``str`` key at all — parsed JSON always has string keys. + """ + assert ops._canonical_op({"v": {18446744073709551615: 1}}) == '{"v":{"18446744073709552000":1}}' + assert ops._canonical_op({"v": {10**21: 1}}) == '{"v":{"1e+21":1}}' + assert ops._canonical_op({"v": {10**400: 1}}) == '{"v":{"Infinity":1}}' + assert ops._canonical_op({"v": {-(10**400): 1}}) == '{"v":{"-Infinity":1}}' + assert ops._canonical_op({"v": {7: 1}}) == '{"v":{"7":1}}' + + def test_object_keys_sort_by_code_point_not_by_utf16_code_unit(): """§8.1's caveat applies to the key sort too: for ASCII, JS UTF-16 ``<`` agrees with code-point order, but above the Basic Multilingual Plane it does From 166ff00d1b05e111f41fbcd025f6df753135910e Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:36:50 +0000 Subject: [PATCH 15/30] fix(workflow): refuse an oversized payload at the charge, not after rendering it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The cost budget was checked only at the end of each `_canonical_value` call. A string is charged by length and then handed to `_canonical_string`, which runs `json.dumps` plus a surrogate scan over the whole thing and allocates up to ~6x its size for control-heavy input — so an oversized string, or an oversized object key at the `+= len(name)` charge, was fully rendered before being refused. A bound that caps the work a hostile payload costs has to refuse at the charge. `_charge` does both, and the outcome is unchanged because the budget only ever grows: every payload that exceeded at the end exceeds at the charge that crossed the line. The trailing check is dropped rather than kept alongside, so there is one refusal site and one message. The shared package already works this way — `opBoundsRefusal` walks and charges the payload before `normalize` renders anything. `op-vocabulary-v1.md` §22 collects this and the integer spelling as v1.11 corrections. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284396 (Low, 4/6 reviewers) --- comfy_cli/workflow_ops.py | 37 ++++++++++++++------ docs/op-vocabulary-v1.md | 34 ++++++++++++++---- tests/comfy_cli/test_op_id_reuse_contract.py | 25 +++++++++++++ 3 files changed, 79 insertions(+), 17 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 2200487a3..1a4ddcc95 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -241,24 +241,41 @@ def _canonical_key(key: Any) -> str: raise ValueError(f"malformed_op: object key of type {type(key).__name__} is not canonical JSON") +def _charge(budget: list[int], units: int) -> None: + """Charge ``units`` against the cost budget and refuse AT the charge. + + Checking only at the end of :func:`_canonical_value` left the bound not + actually bounding the work: a string is charged by length and then handed to + ``_canonical_string``, which runs ``json.dumps`` plus a surrogate scan over + the whole thing and allocates up to ~6x its size for control-heavy input, so + an oversized payload was fully rendered before being refused. The shared + package has the same property for the same reason — ``opBoundsRefusal`` walks + and charges the payload BEFORE ``normalize`` renders anything — and the + refusal is unchanged either way, because the budget only ever grows. + """ + budget[0] += units + if budget[0] > _MAX_OP_COST: + raise ValueError(f"malformed_op: payload exceeds the {_MAX_OP_COST}-unit cost budget") + + def _canonical_value(value: Any, depth: int, budget: list[int]) -> str: if depth > _MAX_OP_PAYLOAD_DEPTH: raise ValueError(f"payload_too_deep: op payload nests deeper than {_MAX_OP_PAYLOAD_DEPTH} levels") - budget[0] += 1 + _charge(budget, 1) if value is None: - budget[0] += 8 + _charge(budget, 8) rendered = "null" elif isinstance(value, bool): # before int: bool is an int subclass - budget[0] += 8 + _charge(budget, 8) rendered = "true" if value else "false" elif isinstance(value, int): # Still a flat 8, deliberately: the cost model is mirrored from the # shared package ("8 per numeric/leaf", `src/limits.ts`), so charging a # huge int by its digit count would refuse a payload CMP accepts. - budget[0] += 8 + _charge(budget, 8) rendered = _es_int(value) elif isinstance(value, float): - budget[0] += 8 + _charge(budget, 8) # ``JSON.stringify`` renders every non-finite number as ``null``, so # doing the same is what makes the two canonical forms agree. It also # un-breaks overwriting a widget whose CURRENT value is NaN/Infinity @@ -266,16 +283,16 @@ def _canonical_value(value: Any, depth: int, budget: list[int]) -> str: # ``old``), which the previous ``allow_nan=False`` rejected outright. rendered = _es_number(value) if math.isfinite(value) else "null" elif isinstance(value, str): - budget[0] += len(value) + _charge(budget, len(value)) rendered = _canonical_string(value) elif isinstance(value, dict): if len(value) > _MAX_OP_COLLECTION_ENTRIES: raise ValueError(f"malformed_op: object exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") - budget[0] += 4 + _charge(budget, 4) members = [] for key in value: name = _canonical_key(key) - budget[0] += len(name) + _charge(budget, len(name)) members.append((name, value[key])) # Unicode code point order at every depth: Python sorts `str` that way. members.sort(key=lambda member: member[0]) @@ -285,12 +302,10 @@ def _canonical_value(value: Any, depth: int, budget: list[int]) -> str: elif isinstance(value, list | tuple): if len(value) > _MAX_OP_COLLECTION_ENTRIES: raise ValueError(f"malformed_op: array exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") - budget[0] += 4 + _charge(budget, 4) rendered = "[" + ",".join(_canonical_value(child, depth + 1, budget) for child in value) + "]" else: raise ValueError(f"malformed_op: op payload is not canonical JSON: {type(value).__name__} is not serializable") - if budget[0] > _MAX_OP_COST: - raise ValueError(f"malformed_op: payload exceeds the {_MAX_OP_COST}-unit cost budget") return rendered diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 93eed71ef..ce10a4da6 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1463,7 +1463,14 @@ precondition — a batch must be within the bound before abort-remainder has anything to say about it — and is otherwise unaltered. Downstream repos pinning this document by SHA move the SHA together with their comfy-cli pin. -## 22. Amendment v1.13 — 2026-10-31 (an integer past 2^53 is spelled as the double it becomes) +## 22. Amendment v1.13 — 2026-10-31 (v1.11 corrections: canonical form and ledger edges) + +Five corrections to Amendment v1.11, all found by review of the implementation +rather than by a failure in the field. None of them re-scopes an op kind and none +needs a change in `comfy-multi-player`; each is comfy-cli coming into line with +what v1.11 and CMP A8 already say. + +### 22.1 An integer past 2^53 is spelled as the double it becomes **§20.1's "numbers rendered as ECMAScript renders them" covers integers too, and comfy-cli did not implement it that way.** It rendered every `int` with Python's @@ -1499,8 +1506,23 @@ The **cost charge is unchanged** at a flat 8 units per number, deliberately: integer by its digit count would refuse a payload CMP accepts — the same validation drift §20.3 withdrew a comfy-cli-only budget to avoid. -**No change to §§1-8, and no change needed in `comfy-multi-player`.** CMP -already produces these spellings, because it canonicalizes with -`JSON.stringify`; this amendment records that comfy-cli now agrees with it. Its -only behavioural effect is on an op carrying an integer past 2^53, which now -digests as its JS spelling. +CMP already produces these spellings, because it canonicalizes with +`JSON.stringify`; this records that comfy-cli now agrees with it. The only +behavioural effect is on an op carrying an integer past 2^53, which now digests +as its JS spelling. + +### 22.2 The cost bound refuses at the charge, not after the render + +§20.3's budget exists to cap the WORK a hostile payload costs, and it was +checked only at the END of each `_canonical_value` call. A string is charged by +length and then handed to the renderer, which runs `json.dumps` plus a surrogate +scan over the whole thing and allocates up to ~6x its size for control-heavy +input — so an oversized string, or an oversized object key at the `+= len(name)` +charge, was fully rendered before being refused. The bound therefore did not +bound the work. + +Charging and refusing at the same point fixes that and changes no outcome, +because the budget only ever grows: every payload that exceeded at the end +exceeds at the charge that crossed the line. The shared package already has this +property for the same reason — `opBoundsRefusal` walks and charges the payload +before `normalize` renders anything. diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index 35ada6713..c688abbd3 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -279,6 +279,31 @@ def test_the_shared_bounds_bind_only_past_any_observed_workflow(): ops._op_digest({"value": "x" * 131_065, "old": "y" * 131_065}) +def test_an_oversized_string_is_refused_before_it_is_rendered(monkeypatch): + """The cost bound exists to cap the WORK a hostile payload costs, so it has + to refuse at the charge rather than after the render. + + ``_canonical_string`` runs ``json.dumps`` plus a surrogate scan over the + whole string and allocates up to ~6x its size for control-heavy input, so + checking the budget only at the end of the call meant the oversized value + was fully rendered first. The shared package charges before it renders for + the same reason (``opBoundsRefusal`` walks the payload ahead of + ``normalize``). The refusal itself is unchanged — the budget only grows. + """ + rendered: list[str] = [] + real = ops._canonical_string + monkeypatch.setattr(ops, "_canonical_string", lambda value: (rendered.append(value), real(value))[1]) + oversized = "x" * (ops._MAX_OP_COST + 1) + + with pytest.raises(ValueError, match=f"^malformed_op: payload exceeds the {ops._MAX_OP_COST}-unit cost budget"): + ops._canonical_op({"v": oversized}) + + assert oversized not in rendered + # Charged per key too, so a dict of oversized keys cannot slip past either. + with pytest.raises(ValueError, match="cost budget"): + ops._canonical_op({"k" * (ops._MAX_OP_COST + 1): 1}) + + def test_canonicalization_still_refuses_a_runaway_payload(): nested: Any = "leaf" for _ in range(ops._MAX_OP_PAYLOAD_DEPTH + 2): From 268e94a11cc281088bf2f929a03a0fba55784086 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:37:38 +0000 Subject: [PATCH 16/30] fix(workflow): refuse object keys that collide after coercion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §20.1 renders an object key as its ECMAScript property-coercion form, and that coercion is not injective: `1` and `"1"`, `True` and `"true"`, `None` and `"null"`, `1.5` and `"1.5"` are distinct Python keys naming the same JS property. Emitting both members produced an object literal no JS object can hold, and because `members.sort` is stable the digest of such a dict then depended on INSERTION order — so the same logical payload could digest two ways and "one `op_id` binds one payload" had a hole in it. Refused as `malformed_op` rather than merged: there is no intent in such a pair that a merge would preserve. Only a programmatically built op can reach the case, since parsed JSON always has `str` keys, so no wire payload changes behaviour — and the test pins that a `str` key which merely looks numeric is untouched. `op-vocabulary-v1.md` §22.3. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284410 (Low, 4/6 reviewers) --- comfy_cli/workflow_ops.py | 14 ++++++++++ docs/op-vocabulary-v1.md | 15 +++++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 27 ++++++++++++++++++++ 3 files changed, 56 insertions(+) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 1a4ddcc95..70e5c7f85 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -290,9 +290,23 @@ def _canonical_value(value: Any, depth: int, budget: list[int]) -> str: raise ValueError(f"malformed_op: object exceeds {_MAX_OP_COLLECTION_ENTRIES} entries") _charge(budget, 4) members = [] + # Coercion is not injective: `1` and `"1"`, `True` and `"true"`, `None` + # and `"null"` are distinct Python keys that name the same JS property. + # Emitting both produces an object literal no JS object can hold, and + # because `members.sort` is stable the digest of such a dict then depends + # on INSERTION order — so the canonical form would not be canonical. + # Only a programmatically built op can reach it (parsed JSON always has + # `str` keys), which is why it is refused rather than silently merged: + # there is no payload here whose intent a merge would preserve. + coerced: dict[str, Any] = {} for key in value: name = _canonical_key(key) _charge(budget, len(name)) + if name in coerced: + raise ValueError( + f"malformed_op: object keys {coerced[name]!r} and {key!r} both canonicalize to {name!r}" + ) + coerced[name] = key members.append((name, value[key])) # Unicode code point order at every depth: Python sorts `str` that way. members.sort(key=lambda member: member[0]) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index ce10a4da6..7d9acb6b9 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1526,3 +1526,18 @@ because the budget only ever grows: every payload that exceeded at the end exceeds at the charge that crossed the line. The shared package already has this property for the same reason — `opBoundsRefusal` walks and charges the payload before `normalize` renders anything. + +### 22.3 Object keys that collide after coercion are `malformed_op` + +§20.1 renders an object key as "its string form, matching ECMAScript property +coercion", and that coercion is not injective: `1` and `"1"`, `True` and +`"true"`, `None` and `"null"`, `1.5` and `"1.5"` are distinct Python keys naming +the same JS property. Emitting both members produced an object literal no JS +object can hold, and because the member sort is stable the digest of such a dict +then depended on INSERTION order — so the same logical payload could digest two +ways and §20's whole "one `op_id`, one payload" guarantee had a hole in it. + +Such a pair is refused as `malformed_op` rather than merged: there is no intent +in it a merge would preserve. Only a programmatically built op can reach the +case at all, since parsed JSON always has `str` keys, so no wire payload +changes behaviour. diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index c688abbd3..f6177e260 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -174,6 +174,33 @@ def test_object_keys_sort_by_code_point_not_by_utf16_code_unit(): assert ops._canonical_op({"\U0001f600": 1, "\uff00": 2}) == '{"\uff00":2,"\U0001f600":1}' +@pytest.mark.parametrize( + ("payload", "name"), + [ + ({1: "a", "1": "b"}, "1"), + ({True: "a", "true": "b"}, "true"), + ({None: "a", "null": "b"}, "null"), + ({1.5: "a", "1.5": "b"}, "1.5"), + ], +) +def test_keys_that_collide_after_coercion_are_refused(payload, name): + """Coercion is not injective, and a canonical form that is not well defined + is not canonical. + + Emitting both members produces an object literal no JS object can hold, and + because the member sort is stable the digest of such a dict would depend on + INSERTION order — so the same logical payload could digest two ways and an + identical redelivery could be read as reuse. Refused rather than merged: + there is no intent here a merge would preserve. Only a programmatically + built op can reach it, since parsed JSON always has ``str`` keys. + """ + with pytest.raises(ValueError, match=rf"^malformed_op: object keys .* both canonicalize to {name!r}"): + ops._canonical_op({"v": payload}) + + # The ordinary case is untouched: a `str` key that merely LOOKS numeric. + assert ops._canonical_op({"v": {name: "b"}}) == f'{{"v":{{"{name}":"b"}}}}' + + def test_a_float_widget_relayed_through_js_digests_the_same(graph): """A FLOAT op whose value is integral comes back from a JS relay as an int. Both spellings have to digest identically, or the identical redelivery is From 9c57953dafad01416a41d794952f829cfcc4b4b5 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:38:48 +0000 Subject: [PATCH 17/30] fix(workflow): tell a missing digest apart from a null one in the ledger MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The legacy-ledger branch was decided with `recorded is None`, which cannot tell a MISSING `_applied_op_digests` entry apart from an explicit `null` one, and the up-front validation checks the ledger's type rather than its values — both arrive from the same untrusted JSON. A document carrying `{: null}` therefore read as a legacy list-only ledger and returned a changed-payload redelivery as a silent no-op: exactly the divergence Amendment v1.11 exists to stop. Every other non-string value failed closed on the digest comparison, so null was the one shape that failed open. The legacy case is now membership, and a present-but-non-string entry is `malformed_op` rather than `op_id_reuse` — the document's bookkeeping is broken, which is not the same finding as a sender reusing an id, and an identical redelivery is refused too because there is no digest left to recognise it by. Refused on read rather than by walking every entry on every apply. `op-vocabulary-v1.md` §22.4. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284401 (Low, 3/6 reviewers) --- comfy_cli/workflow_ops.py | 18 +++++++- docs/op-vocabulary-v1.md | 18 ++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 48 ++++++++++++++++++++ 3 files changed, 82 insertions(+), 2 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 70e5c7f85..d0eb25093 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3754,13 +3754,27 @@ def apply_op(workflow: dict, op: dict, graph) -> dict: recorded_digests = workflow.get("_applied_op_digests") recorded_ops = workflow.get("_applied_ops") if op_id in (recorded_ops or ()): - recorded = (recorded_digests or {}).get(op_id) - if recorded is None: + ledger = recorded_digests if isinstance(recorded_digests, dict) else {} + # MEMBERSHIP, not ``.get(...) is None``: a document carrying + # ``{: null}`` has a digest entry, it just has a malformed one. + # Reading its absence as "legacy list-only ledger" made a + # changed-payload redelivery a silent no-op on exactly the shape the + # up-front check does not cover — every other non-string value failed + # closed on the ``!=`` below, so null was the one that failed open. + if op_id not in ledger: # A legacy list-only ledger keeps its historical duplicate # behaviour, and deliberately WITHOUT digesting the payload first: # a replay whose envelope is not canonical must still be the # documented no-op rather than a ``malformed_op``. return workflow + recorded = ledger[op_id] + # The up-front check validates the ledger's TYPE, not its values, and + # both arrive from the same untrusted JSON. Refused on read rather than + # by walking every entry on every apply. + if not isinstance(recorded, str): + raise ValueError( + f"malformed_op: _applied_op_digests[{op_id!r}] must be a string digest, got {type(recorded).__name__}" + ) if recorded != _op_digest(op): raise ValueError(f"op_id_reuse: op_id {op_id!r} was already applied with a different payload") return workflow diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 7d9acb6b9..865b6e8b6 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1541,3 +1541,21 @@ Such a pair is refused as `malformed_op` rather than merged: there is no intent in it a merge would preserve. Only a programmatically built op can reach the case at all, since parsed JSON always has `str` keys, so no wire payload changes behaviour. + +### 22.4 A `null` digest entry is malformed, not a legacy ledger + +§20.2's "legacy documents are untouched" rule is keyed on a document having +`_applied_ops` and **no** `_applied_op_digests` entry for the op. comfy-cli +decided that with `recorded is None`, which cannot tell a MISSING entry apart +from an explicit `null` one, and the up-front validation checks the ledger's +type rather than its values — both arrive from the same untrusted JSON. + +So a document carrying `{: null}` read as a legacy list-only ledger and +returned a changed-payload redelivery as a silent no-op, which is precisely the +divergence v1.11 exists to stop. Every other non-string value failed closed on +the digest comparison, so `null` was the one shape that failed open. + +The legacy case is now decided by MEMBERSHIP, and a present-but-non-string +digest entry is `malformed_op` — not `op_id_reuse`, because the document's +bookkeeping is broken rather than the sender's id being reused. It is refused on +read rather than by walking every ledger entry on every apply. diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index f6177e260..a0f51179c 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -398,6 +398,54 @@ def test_a_truthy_non_dict_ledger_is_refused_on_the_reuse_branch_too(graph): ops.apply_op(workflow, applied, graph) +def test_a_null_digest_entry_is_not_read_as_a_legacy_ledger(graph): + """``recorded is None`` could not tell a MISSING digest apart from an + explicit ``null`` one, and the up-front check validates the ledger's type + rather than its values. + + So a document carrying ``{: null}`` read as "legacy list-only ledger" + and returned a changed-payload redelivery as a silent no-op — the exact + divergence Amendment v1.11 exists to stop. Every other non-string value + failed closed on the digest comparison, so ``null`` was the one shape that + failed OPEN. Red on the parent, which returns the workflow unchanged. + """ + workflow = _workflow() + ops.apply_op(workflow, _op(25), graph) + workflow["_applied_op_digests"][_op()["op_id"]] = None + before = copy.deepcopy(workflow) + + with pytest.raises(ValueError, match=r"^malformed_op: _applied_op_digests\[.*\] must be a string digest"): + ops.apply_op(workflow, _op(30), graph) + assert workflow == before + + +@pytest.mark.parametrize("recorded", [None, 7, ["digest"], {"d": 1}, True]) +def test_a_non_string_digest_entry_is_malformed_not_a_mismatch(graph, recorded): + """``malformed_op``, not ``op_id_reuse``: the document's bookkeeping is + broken, which is not the same finding as a sender reusing an id. An + IDENTICAL redelivery is refused too — there is no recorded digest to + recognise it by. + """ + workflow = _workflow() + applied = _op(25) + ops.apply_op(workflow, applied, graph) + workflow["_applied_op_digests"][applied["op_id"]] = recorded + with pytest.raises(ValueError, match="^malformed_op: _applied_op_digests"): + ops.apply_op(workflow, applied, graph) + + +def test_a_legacy_list_only_ledger_is_still_a_silent_no_op(graph): + """The complement: a document with ``_applied_ops`` and NO digest entry + keeps its historical drop-the-duplicate behaviour, and keeps it without + digesting the replayed payload first.""" + workflow = _workflow() + applied = _op(25) + ops.apply_op(workflow, applied, graph) + del workflow["_applied_op_digests"][applied["op_id"]] + assert ops.apply_op(workflow, _op(30), graph) is workflow + assert workflow["nodes"][0]["widgets_values"] == [25] + + @pytest.mark.parametrize("op_id", [["a"], {"a": 1}, 7, None]) def test_a_non_string_op_id_is_refused_before_the_handler_runs(graph, op_id): workflow = _workflow() From ad68d4422a0cefee9287f79743e2a4fb0540d334 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:40:23 +0000 Subject: [PATCH 18/30] fix(workflow): digest a queued deferred op defensively, not strictly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The deferred-queue reuse gate digested the QUEUED entry with `_op_digest`, under a comment claiming it could not raise because a queued op was canonicalized on the way in. `_deferred_widget_ops` comes off the document and is never validated on load, so that does not hold — `_retry_deferred_widget_ops` already drops uncanonical queued entries for exactly this reason. An oversized or deeply nested queued entry therefore raised its own `malformed_op:` / `payload_too_deep:` against the INCOMING op: a well-formed op blocked by an error naming a payload that is not the one being applied. `_applied_digest` returns None there instead, and None is a mismatch — correctly, because the incoming op has already been digested by that point and is therefore canonical, so an uncanonical queued entry cannot be the same payload. The refusal is `op_id_reuse`, which is what it is. Red on the parent with `payload_too_deep`. `op-vocabulary-v1.md` §22.5. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284428 (Nit, 3/6 reviewers) --- comfy_cli/workflow_ops.py | 12 +++++- docs/op-vocabulary-v1.md | 16 ++++++++ .../test_dynamic_combo_other_option_widget.py | 38 +++++++++++++++++++ 3 files changed, 64 insertions(+), 2 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index d0eb25093..c39537578 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3792,8 +3792,16 @@ def apply_op(workflow: dict, op: dict, graph) -> dict: # different orders diverge silently. queued = workflow.get("_deferred_widget_ops") waiting = queued.get(op_id) if isinstance(queued, dict) else None - # Cannot raise: a queued op was canonicalized on the way in. - if isinstance(waiting, dict) and _op_digest(waiting) != digest: + # ``_applied_digest``, not ``_op_digest``: ``_deferred_widget_ops`` comes off + # the DOCUMENT and is never validated on load, so an oversized or deeply + # nested queued entry raised its own ``malformed_op:``/``payload_too_deep:`` + # here — against the incoming op, blocking it (even as an identical + # redelivery) with an error naming a payload that is not the one being + # applied. ``None`` is a mismatch, and correctly so: the op above was just + # digested, so it IS canonical, and an uncanonical queued entry therefore + # cannot be the same payload. ``_retry_deferred_widget_ops`` already treats + # an uncanonical queued entry as unusable for the same reason. + if isinstance(waiting, dict) and _applied_digest(waiting) != digest: raise ValueError(f"op_id_reuse: op_id {op_id!r} is already deferred with a different payload") had_applied_ops = "_applied_ops" in workflow workflow.setdefault("_applied_ops", []) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 865b6e8b6..8883f1ea0 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1559,3 +1559,19 @@ The legacy case is now decided by MEMBERSHIP, and a present-but-non-string digest entry is `malformed_op` — not `op_id_reuse`, because the document's bookkeeping is broken rather than the sender's id being reused. It is refused on read rather than by walking every ledger entry on every apply. + +### 22.5 The deferred-queue digest is taken defensively + +§20.2's deferred-queue gate digested the QUEUED entry with the strict +canonicalizer, under a comment claiming it could not raise because a queued op +was canonicalized on the way in. `_deferred_widget_ops` comes off the document +and is never validated on load, so that does not hold: an oversized or deeply +nested queued entry raised its own `malformed_op:` / `payload_too_deep:` against +the INCOMING op, blocking a well-formed op with an error naming a payload that +is not the one being applied. + +The queued entry is now digested with the same tolerant helper the retry loop +uses, and a `None` digest is a mismatch — correctly, because the incoming op has +already been digested at that point and is therefore canonical, so an +uncanonical queued entry cannot be the same payload. The refusal is +`op_id_reuse`, which is what it is. diff --git a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py index fa91a98f8..d2525983f 100644 --- a/tests/comfy_cli/test_dynamic_combo_other_option_widget.py +++ b/tests/comfy_cli/test_dynamic_combo_other_option_widget.py @@ -600,6 +600,44 @@ def test_a_deferred_write_is_bound_to_its_canonical_payload_once_applied(graph): assert wf == before +def test_an_uncanonical_queued_entry_does_not_block_with_the_wrong_error(graph): + """``_deferred_widget_ops`` comes off the DOCUMENT and is never validated on + load, so the queued entry is not guaranteed canonical the way the comment + here used to claim. + + Digesting it with ``_op_digest`` raised its own ``payload_too_deep:`` / + ``malformed_op:`` against the INCOMING op — an error naming a payload that + is not the one being applied, on an op that may be perfectly well formed. + ``_applied_digest`` returns ``None`` instead, which is a mismatch: the + incoming op was already digested above, so it is canonical, and an + uncanonical queued entry cannot be the same payload. The refusal is + therefore ``op_id_reuse``, which is what it actually is. + """ + wf, node_id = _fresh(graph) + hidden_write = workflow_ops._new_op( + "set_widget", + "agent-a", + 1, + node_id=node_id, + widget="model.prompt_expansion_mode", + value="quality", + ) + workflow_ops.apply_op(wf, hidden_write, graph) + assert hidden_write["op_id"] in wf["_deferred_widget_ops"] + + # Only a hand-edited document can get here, which is the point: nothing + # validates this on load. + nested = "leaf" + for _ in range(workflow_ops._MAX_OP_PAYLOAD_DEPTH + 2): + nested = [nested] + wf["_deferred_widget_ops"][hidden_write["op_id"]]["value"] = nested + before = copy.deepcopy(wf) + + with pytest.raises(ValueError, match="^op_id_reuse:"): + workflow_ops.apply_op(wf, copy.deepcopy(hidden_write), graph) + assert wf == before + + def test_a_second_payload_on_a_deferred_op_id_is_refused_rather_than_overwriting_it(graph): """The reuse gate used to read ``_applied_ops`` only. A deferred write sits in ``_deferred_widget_ops`` and nowhere else, so a second op carrying the From 402399161be3bfef5d0a84615dde8ac9124dd3b1 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:41:05 +0000 Subject: [PATCH 19/30] fix(workflow): validate an op's kind before seeding the applied ledger MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `kind = op["op"]` and the `definitions`-on-a-non-insert refusal sat after `workflow.setdefault("_applied_ops", [])`, and both raise outside the handler rollback. So a first-seen op with no `op` key, or a non-insert op carrying `definitions`, was correctly rejected and still left `{"_applied_ops": []}` behind on a document that arrived with no ledger — contradicting Amendment v1.11's "a document that arrived without a ledger is never left carrying an empty one by a rejected op". Both validations move above the seed. No message or code changes; the two new cases are red on the parent. `op-vocabulary-v1.md` §22.6. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284420 (Low, 2/6 reviewers) --- comfy_cli/workflow_ops.py | 10 ++++++-- docs/op-vocabulary-v1.md | 12 ++++++++++ tests/comfy_cli/test_op_id_reuse_contract.py | 24 ++++++++++++++++++++ 3 files changed, 44 insertions(+), 2 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index c39537578..90934e127 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -3803,11 +3803,17 @@ def apply_op(workflow: dict, op: dict, graph) -> dict: # an uncanonical queued entry as unusable for the same reason. if isinstance(waiting, dict) and _applied_digest(waiting) != digest: raise ValueError(f"op_id_reuse: op_id {op_id!r} is already deferred with a different payload") - had_applied_ops = "_applied_ops" in workflow - workflow.setdefault("_applied_ops", []) + # BEFORE the ``setdefault`` below, because both of these raise OUTSIDE the + # rollback: a first-seen op with no ``op`` key, or a non-insert op carrying + # ``definitions``, is rejected and used to leave an empty ``_applied_ops`` + # on a document that arrived without one — contradicting §20.2's "a document + # that arrived without a ledger is never left carrying an empty one by a + # rejected op". kind = op["op"] if kind != "insert_workflow" and "definitions" in op: raise ValueError(f"malformed_op: {kind} does not accept definitions") + had_applied_ops = "_applied_ops" in workflow + workflow.setdefault("_applied_ops", []) # Snapshot the LWW bookkeeping so an exception escaping a handler cannot # leave a stamp committed WITHOUT its op_id recorded below. That pairing is # the poison state: a retry of the identical op loses to the failed diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 8883f1ea0..76a176219 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1575,3 +1575,15 @@ uses, and a `None` digest is a mismatch — correctly, because the incoming op h already been digested at that point and is therefore canonical, so an uncanonical queued entry cannot be the same payload. The refusal is `op_id_reuse`, which is what it is. + +### 22.6 Kind and `definitions` are validated before the ledger is seeded + +§20.2 promises that "a document that arrived without a ledger is never left +carrying an empty one by a rejected op". Two validations sat on the wrong side of +that line: the read of the op's `op` field, and the refusal of `definitions` on +a non-`insert_workflow` op, both ran after `_applied_ops` had been seeded and +both raise outside the handler rollback. So a first-seen op with no `op` key, or +a non-insert op carrying `definitions`, was correctly rejected and left +`{"_applied_ops": []}` behind on a document that had no ledger at all. + +Both now run before the seed. No message or code changes. diff --git a/tests/comfy_cli/test_op_id_reuse_contract.py b/tests/comfy_cli/test_op_id_reuse_contract.py index a0f51179c..8e8c629a5 100644 --- a/tests/comfy_cli/test_op_id_reuse_contract.py +++ b/tests/comfy_cli/test_op_id_reuse_contract.py @@ -350,6 +350,30 @@ def test_canonicalization_still_refuses_a_runaway_payload(): # --- Amendment v1.10: rejecting before mutation ----------------------------- +@pytest.mark.parametrize( + ("mutate", "exc"), + [ + (lambda op: op.pop("op"), KeyError), + (lambda op: op.update(definitions={"x": {}}), ValueError), + ], + ids=["no-op-key", "definitions-on-a-non-insert-op"], +) +def test_a_rejected_op_leaves_no_empty_ledger_behind_either(graph, mutate, exc): + """Both of these validations raise OUTSIDE ``apply_op``'s rollback, so when + they ran after ``setdefault("_applied_ops", [])`` a rejected op left an empty + ledger on a document that arrived without one — contradicting the §20.2 + guarantee the amendment states. Red on the parent, which comes back carrying + ``{"_applied_ops": []}``. + """ + workflow = _workflow() + before = copy.deepcopy(workflow) + bad = _op() + mutate(bad) + with pytest.raises(exc): + ops.apply_op(workflow, bad, graph) + assert workflow == before + + def test_a_rejected_first_seen_op_leaves_no_ledger_behind(graph): """ "Rejects before mutation" has to include the ledger itself: a document that arrived without ``_applied_ops`` must not come back carrying an empty From 8d3f190c186e9f3fc6be69ee96a8ee329523d8a6 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:42:58 +0000 Subject: [PATCH 20/30] fix(workflow): bound each op replace_ops mints, not only the batch length MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `apply_specs`' ops each go through `apply_op`, which canonicalizes them, so §20.3's per-op bounds (depth 64, 4,096 entries, 262,144 cost) are enforced on that path. `replace_ops` builds its ops and hands them straight to a caller, so nothing checked them at all: a node with an outsized `widgets_values`, or a `delete_node` whose `removed_links` runs past the entry cap, produced a batch `templates fetch --emit-ops` presented as the legal translation of the graph and the shared applier then refused whole as `malformed_op`. The same mint-then-refuse shape the batch bound closes, one level down. Canonicalized rather than digested — the refusal is the point and the hash is not needed — and reported as `NotExpressibleError` with the op index and kind, so both production callers keep the behaviour they already implement for the other two reasons. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284394 (Low, 3/6 reviewers) --- comfy_cli/workflow_ops.py | 15 +++++++ docs/op-vocabulary-v1.md | 10 +++-- tests/comfy_cli/test_max_ops_per_batch.py | 55 +++++++++++++++++++++++ 3 files changed, 76 insertions(+), 4 deletions(-) diff --git a/comfy_cli/workflow_ops.py b/comfy_cli/workflow_ops.py index 90934e127..81633b2c6 100644 --- a/comfy_cli/workflow_ops.py +++ b/comfy_cli/workflow_ops.py @@ -2995,6 +2995,21 @@ def replace_ops(old: dict, new: dict, *, actor: str = "cli", base_version: int = f"the workflow needs {len(ops)} ops, more than the {_MAX_OPS_PER_BATCH}-op batch limit " "(delete_node per existing node, add_node per node, connect per link)" ) + # The batch length is only the outer bound. These ops are built here and + # handed straight to a caller — unlike `apply_specs`', every one of which + # goes through `apply_op` and is canonicalized there — so nothing had + # checked the PER-OP payload bounds (§20.3: depth 64, 4,096 entries, 262,144 + # cost). A node with an outsized `widgets_values`, or a `delete_node` whose + # `removed_links` runs past the entry cap, produced a batch this function + # presented as the legal translation of the graph and the shared applier + # then refused as `malformed_op`: the same mint-then-refuse shape one level + # down. Canonicalized rather than digested, since the refusal is the whole + # point and the hash is not needed. + for i, minted in enumerate(ops): + try: + _canonical_op(minted) + except ValueError as e: + raise NotExpressibleError(f"op #{i} ({minted['op']}) is not a legal op payload: {e}") from e return ops diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 76a176219..ca06c7071 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1433,10 +1433,12 @@ Where it is enforced, and the two different refusals: raises `malformed_op: batch mints ops, more than the 1024-op limit`; `applied_count` is 0 there like every other mid-batch refusal. * **`replace_ops`** raises **`NotExpressibleError`**, the existing "there is no - legal batch for this graph" signal, rather than a bare `ValueError`. Its two - reasons are now *structure no frozen kind can create* and *a translation - longer than the bound*; both want the same caller behaviour, which both - production callers already implement — `templates fetch --emit-ops` reports + legal batch for this graph" signal, rather than a bare `ValueError`. Its + reasons are now *structure no frozen kind can create*, *a translation longer + than the bound*, and *one op whose own payload is out of §20.3's bounds* — + that last one because these ops are handed to a caller without ever passing + through `apply_op`, so nothing else canonicalizes them. All three want the + same caller behaviour, which both production callers already implement — `templates fetch --emit-ops` reports `ops_skipped` beside the file it still wrote, and `generate`'s emit path raises `EmitError`. The count binds on the SUM of `old` and `new`, because §8.8's replacement shape emits a `delete_node` per node already in `old` diff --git a/tests/comfy_cli/test_max_ops_per_batch.py b/tests/comfy_cli/test_max_ops_per_batch.py index fe8e3b5c0..d507d296c 100644 --- a/tests/comfy_cli/test_max_ops_per_batch.py +++ b/tests/comfy_cli/test_max_ops_per_batch.py @@ -182,6 +182,61 @@ def test_the_old_document_counts_toward_the_batch_too(): ops.replace_ops(_nodes(600), _nodes(600)) +# --- the per-op payload bounds, on a batch nothing applies ------------------ + + +def test_replace_ops_refuses_an_op_whose_own_payload_is_out_of_bounds(): + """The batch length is only the OUTER bound. + + ``apply_specs``' ops each go through ``apply_op``, which canonicalizes them + and so enforces §20.3's per-op bounds (depth 64, 4,096 entries, 262,144 + cost). ``replace_ops`` builds its ops and hands them straight to a caller, + so nothing checked those — and ``templates fetch --emit-ops`` presented the + result as the legal translation of the graph while the shared applier + refused it whole as ``malformed_op``. Same mint-then-refuse shape, one level + down. + """ + # A `widgets_values` past the entry cap: copied verbatim into `add_node`. + oversized = { + "nodes": [ + { + "id": 1, + "type": "KSampler", + "widgets_values": [0] * (ops._MAX_OP_COLLECTION_ENTRIES + 1), + "inputs": [], + "outputs": [], + } + ], + "links": [], + } + with pytest.raises(ops.NotExpressibleError, match=r"op #0 \(add_node\) is not a legal op payload: .*entries"): + ops.replace_ops({"nodes": [], "links": []}, oversized) + + # And by cost, from one very long widget string. + costly = { + "nodes": [ + { + "id": 1, + "type": "KSampler", + "widgets_values": ["x" * (ops._MAX_OP_COST + 1)], + "inputs": [], + "outputs": [], + } + ], + "links": [], + } + with pytest.raises(ops.NotExpressibleError, match=r"not a legal op payload: .*cost budget"): + ops.replace_ops({"nodes": [], "links": []}, costly) + + +def test_the_per_op_check_leaves_an_ordinary_batch_alone(): + """It refuses a payload the shared applier would refuse, and nothing else: + every op a real graph mints is orders of magnitude inside the bounds.""" + minted = ops.replace_ops(_nodes(4), _nodes(8)) + assert len(minted) == 12 + assert all(len(ops._op_digest(op)) == 64 for op in minted) + + # --- where it actually bites, measured rather than assumed ------------------ From 2b3e75698fbb8a3bfca751d6c70e285078004ebe Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:54:37 +0000 Subject: [PATCH 21/30] fix(generate): skip the op batch instead of discarding a good workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `replace_ops` emits a `delete_node` per node ALREADY at the target path, so a `--emit-workflow --emit-ops` run against a path that holds a large workflow pushes the batch past the 1,024-op bound even though the graph being written is tiny. `write_frontend_workflow` raised `EmitError` there, before the write, so nothing was saved at all — and the umbrella `emit_workflow_failed` hint told the caller to check the model name and that all required inputs are provided, for a failure neither of them caused. The branch was commented as can't-happen for our own built graph, which is true of the STRUCTURAL reason and not of this one: `previous` is ordinary user data at a path the user named. `templates fetch --emit-ops` already degrades on the same condition, so this matches it: the file is written, `ops` is None, and `ops_skipped` carries the reason in the same envelope key. `write_frontend_workflow` returns `(workflow, ops, ops_skipped)`; `generate emit-workflow` has no registered result schema, so the added key breaks no consumer contract. Red on the parent with `EmitError` and no file on disk. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430284415 (Low, 2/6 reviewers) --- comfy_cli/command/generate/app.py | 9 +++- comfy_cli/command/generate/emit.py | 36 ++++++++++---- .../command/generate/test_emit_ops.py | 48 +++++++++++++++++-- 3 files changed, 79 insertions(+), 14 deletions(-) diff --git a/comfy_cli/command/generate/app.py b/comfy_cli/command/generate/app.py index 0585df524..642b7c438 100644 --- a/comfy_cli/command/generate/app.py +++ b/comfy_cli/command/generate/app.py @@ -593,6 +593,7 @@ def _track_error(error_kind: str, exc: BaseException) -> None: prefix = meta.get("output-prefix") if isinstance(meta.get("output-prefix"), str) else "generate" renderer = get_renderer() ops: list | None = None + ops_skipped: str | None = None from comfy_cli import workflow_ops try: @@ -625,7 +626,7 @@ def _track_error(error_kind: str, exc: BaseException) -> None: # is left without its terminal event. _track_error("emit", e) raise - workflow, ops = emit.write_frontend_workflow( + workflow, ops, ops_skipped = emit.write_frontend_workflow( name, values, Path(emit_path).expanduser(), @@ -691,6 +692,12 @@ def _track_error(error_kind: str, exc: BaseException) -> None: } if ops is not None: payload["ops"] = ops + elif ops_skipped: + # Same envelope key `templates fetch --emit-ops` uses: the file + # was written, the batch was not minted, and this says why so a + # consumer can fall back to the whole-document path instead of + # guessing from a missing key. + payload["ops_skipped"] = ops_skipped renderer.emit(payload, command="generate emit-workflow") return diff --git a/comfy_cli/command/generate/emit.py b/comfy_cli/command/generate/emit.py index 2bce3a439..d1bd1435b 100644 --- a/comfy_cli/command/generate/emit.py +++ b/comfy_cli/command/generate/emit.py @@ -618,12 +618,22 @@ def write_frontend_workflow( actor: str = "cli", base_version: int = 0, output_prefix: str = "generate", -) -> tuple[dict[str, Any], list[dict[str, Any]]]: +) -> tuple[dict[str, Any], list[dict[str, Any]] | None, str | None]: """Build the workflow for ``model`` as a FRONTEND-format graph and write it - to ``path``; return ``(workflow, ops)`` where ``ops`` is the stamped - ``replace_ops`` batch that turns whatever ``path`` previously held into the - new graph (empty previous ⇒ no delete half), ready for the envelope exactly - like ``templates fetch --emit-ops``. + to ``path``; return ``(workflow, ops, ops_skipped)`` where ``ops`` is the + stamped ``replace_ops`` batch that turns whatever ``path`` previously held + into the new graph (empty previous ⇒ no delete half), ready for the envelope + exactly like ``templates fetch --emit-ops``. + + ``ops`` is ``None`` with ``ops_skipped`` set when the batch cannot be minted. + That is NOT a failure of the request — the file is written either way, and a + consumer falls back to the whole-document path it had before ops existed, + exactly as ``templates fetch --emit-ops`` does. The reason it can happen at + all is the PREVIOUS document: ``replace_ops`` emits a ``delete_node`` per + node already at ``path``, so a target that holds a large workflow can push + the batch past the 1,024-op bound even though the graph being written is + tiny. That is ordinary user data, not a bug in the built graph, so failing + the whole command over it would discard a workflow that is perfectly good. Raises ``EmitError``/``UnsupportedModelError`` like :func:`write_workflow`; an applier failure surfaces as ``EmitError`` (the request itself was @@ -665,10 +675,20 @@ def write_frontend_workflow( # `replace_ops` so the returned workflow, the file and the batch describe # one document. workflow_ops.strip_internal(workflow) + ops: list[dict[str, Any]] | None = None + ops_skipped: str | None = None try: ops = workflow_ops.replace_ops(previous, workflow, actor=actor, base_version=base_version) - except workflow_ops.NotExpressibleError as e: # can't-happen for our own built graph; fail loudly if it does - raise EmitError(f"the {model!r} workflow cannot be expressed as ops: {e}") from e + except workflow_ops.NotExpressibleError as e: + # Non-fatal, like `templates fetch --emit-ops`: the workflow itself is + # fine and still gets written. This used to be commented as can't-happen + # for our own built graph, and for the STRUCTURAL reason it is — but the + # batch also counts a `delete_node` per node already at `path`, which is + # user data, so a large existing file could fail the whole command and + # write nothing. The umbrella `emit_workflow_failed` hint then told the + # caller to check the model name and its required inputs, for a failure + # neither of them caused. + ops_skipped = str(e) path.parent.mkdir(parents=True, exist_ok=True) path.write_text(json.dumps(workflow, indent=2) + "\n", encoding="utf-8") - return workflow, ops + return workflow, ops, ops_skipped diff --git a/tests/comfy_cli/command/generate/test_emit_ops.py b/tests/comfy_cli/command/generate/test_emit_ops.py index 711677c4f..79bee2489 100644 --- a/tests/comfy_cli/command/generate/test_emit_ops.py +++ b/tests/comfy_cli/command/generate/test_emit_ops.py @@ -304,7 +304,7 @@ def test_ops_fold_multiple_images_through_image_batch(): def test_write_frontend_workflow_writes_frontend_and_returns_replace_batch(tmp_path): out = tmp_path / "workflow.json" - wf, ops = emit.write_frontend_workflow( + wf, ops, _skipped = emit.write_frontend_workflow( "nano-banana", {"prompt": "add sunglasses", "image": "cat.png"}, out, @@ -322,16 +322,54 @@ def test_write_frontend_workflow_writes_frontend_and_returns_replace_batch(tmp_p def test_write_frontend_workflow_emits_delete_half_over_a_previous_graph(tmp_path): out = tmp_path / "workflow.json" - _wf1, _ops1 = emit.write_frontend_workflow( + _wf1, _ops1, _s1 = emit.write_frontend_workflow( "flux-2", {"prompt": "first"}, out, _graph(), actor="agent", base_version=0 ) - _wf2, ops2 = emit.write_frontend_workflow( + _wf2, ops2, _s2 = emit.write_frontend_workflow( "nano-banana", {"prompt": "second", "image": "cat.png"}, out, _graph(), actor="agent", base_version=1 ) deletes = [o for o in ops2 if o["op"] == "delete_node"] assert deletes, "replacing an existing canvas must delete what it replaces, like templates fetch" +def test_a_large_existing_file_skips_the_batch_instead_of_discarding_the_workflow(tmp_path): + """``replace_ops`` emits a ``delete_node`` per node ALREADY at the target + path, so a target holding a big workflow pushes the batch past the 1,024-op + bound even though the graph being written is tiny. + + That is ordinary user data at a path the user named, not a bug in the built + graph. Raising turned it into an ``EmitError`` before the write, so nothing + was saved at all and the umbrella hint told the caller to check the model + name and its required inputs — for a failure neither of them caused. + ``templates fetch --emit-ops`` already degrades on the same condition, and + this now matches it: the file is written, ``ops`` is ``None``, and + ``ops_skipped`` says why. Red on the parent with ``EmitError``. + """ + out = tmp_path / "workflow.json" + out.write_text( + json.dumps( + { + "nodes": [ + {"id": i + 1, "type": "LoadImage", "widgets_values": ["example.png"], "inputs": [], "outputs": []} + for i in range(workflow_ops._MAX_OPS_PER_BATCH + 1) + ], + "links": [], + } + ), + encoding="utf-8", + ) + + wf, ops, ops_skipped = emit.write_frontend_workflow( + "flux-2", {"prompt": "first"}, out, _graph(), actor="agent", base_version=0 + ) + + assert ops is None + assert "1024-op batch limit" in ops_skipped + # The workflow itself is good and is on disk, which is the deliverable. + assert json.loads(out.read_text()) == wf + assert isinstance(wf.get("nodes"), list) and wf["nodes"] + + def test_write_frontend_workflow_unsupported_model_still_raises(tmp_path): with pytest.raises(emit.UnsupportedModelError): emit.write_frontend_workflow("no-such-model", {}, tmp_path / "w.json", _graph()) @@ -454,7 +492,7 @@ def test_write_frontend_workflow_strips_apply_bookkeeping_before_write_and_batch next edit. Strip BEFORE ``replace_ops`` so the returned workflow, the file and the batch all describe the same document.""" out = tmp_path / "workflow.json" - wf, ops = emit.write_frontend_workflow( + wf, ops, _skipped = emit.write_frontend_workflow( "nano-banana", {"prompt": "ORIGINAL", "image": "cat.png"}, out, _graph(), actor="agent", base_version=7 ) on_disk = json.loads(out.read_text()) @@ -502,7 +540,7 @@ def test_write_frontend_workflow_materializes_nano_banana_pro_from_the_nightly_i options for model — closest: gemini-2.5-flash-image" — because emit built GeminiImageNode. #921 routes that model to GeminiImage2Node; this replays that input through the same frontend (canvas-ops) path.""" - wf, ops = emit.write_frontend_workflow( + wf, ops, _skipped = emit.write_frontend_workflow( "nano-banana", { "prompt": "Redraw this character as 16-bit pixel art.", From 3e065b009bc1bd6197198d9522fb644a1384ff89 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 06:55:28 +0000 Subject: [PATCH 22/30] docs(changelog): say what the 50-op gallery measurement does not cover MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The entry claimed "no real workflow is affected". That measured the `new` side only: `replace_ops` also emits a `delete_node` per node already in the file being replaced, which is user data bounded by nothing the measurement saw. A fetch or an emit into a path that already holds a workflow of about a thousand nodes can exceed the bound while the incoming template is small, so the claim was too strong. The entry now says where the bound can be reached and that both callers keep the file and skip the batch there. §21's headroom paragraph and the headroom test's docstring carry the same caveat, and a second entry records the integer-spelling change, which is the only one of these with a visible effect on a digest. Addresses: https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4430123057 (CodeRabbit) --- CHANGELOG.md | 30 ++++++++++++++++++----- docs/op-vocabulary-v1.md | 12 ++++++--- tests/comfy_cli/test_max_ops_per_batch.py | 10 ++++++-- 3 files changed, 41 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index abffa7494..ff19b8260 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -191,12 +191,30 @@ history. ### Changed - A structured-edit batch is bounded at 1,024 ops, the limit the shared - `comfy-multi-player` applier already enforces. `comfy workflow apply` refuses - a longer batch before any spec is processed and writes nothing, and - `templates fetch --emit-ops` reports `ops_skipped` beside the workflow file it - still writes rather than emitting a batch that would be rejected whole on - arrival. Measured over the whole template gallery, the longest batch this path - actually produces is 50 ops, so no real workflow is affected. + `comfy-multi-player` applier already enforces, and each op in it is bounded by + the per-op payload limits that applier applies. `comfy workflow apply` refuses + a longer batch and writes nothing — counting the ops the specs actually mint, + since one `set_dynamic_group_rows` spec expands into a write per row field. + `templates fetch --emit-ops` and `generate --emit-workflow --emit-ops` report + `ops_skipped` beside the workflow file they still write, rather than emitting + a batch that would be rejected whole on arrival. + + Where the bound can be reached: the measurement behind it covered the + workflows being written — over the whole template gallery the longest batch + that path produces is 50 ops — and a replacement also emits a `delete_node` + per node already in the file being replaced, which is not bounded by anything + this measurement saw. So a fetch or an emit into a path that already holds a + workflow of about a thousand nodes can exceed the bound while the incoming + template is small. That case now skips the batch and keeps the file, where an + emit previously failed and wrote nothing. + +- An integer past 2^53 in an op payload is digested as the double it becomes, + the way ECMAScript spells it, rather than as its exact Python digits. JSON + carries no integer type, so a relay through the shared applier rounds such a + value — a seed at `0xffffffffffffffff` comes back as `18446744073709552000` — + and digesting the exact digits made an identical op echoed back look like a + changed payload reusing its `op_id`. Integers inside that range, which is + every id, stamp and ordinary widget value, are unaffected. - Once every model byte is in, the progress line of `comfy deploy up`, `comfy deploy status` (with or without `--watch`) and a watching diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index ca06c7071..26e5a6f5a 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1444,9 +1444,15 @@ Where it is enforced, and the two different refusals: §8.8's replacement shape emits a `delete_node` per node already in `old` before the adds. -Measured headroom. Across all 735 workflows in `Comfy-Org/workflow_templates` — -the gallery `templates fetch --emit-ops` reads — the longest batch `replace_ops` -actually mints is **50 ops**, 4.9% of the bound. 447 of those templates carry a +Measured headroom, and what the measurement does NOT cover. Across all 735 +workflows in `Comfy-Org/workflow_templates` — the gallery +`templates fetch --emit-ops` reads — the longest batch `replace_ops` actually +mints is **50 ops**, 4.9% of the bound. That measured the `new` side only. The +`old` side is whatever document the caller is replacing, which is user data and +is bounded by nothing here: a fetch or an emit into a path already holding a +workflow of ~1,000 nodes can exceed the bound on the `delete_node` half alone +while the incoming template is tiny. Both callers degrade rather than fail on +that case (`ops_skipped` beside a file they still write). 447 of those templates carry a subgraph definition, a canvas group or a reroute point and are refused as inexpressible before size is considered; across all 735, nodes+links peaks at 212, so even if every one of them became expressible the worst case stays a fifth diff --git a/tests/comfy_cli/test_max_ops_per_batch.py b/tests/comfy_cli/test_max_ops_per_batch.py index d507d296c..5abbb229e 100644 --- a/tests/comfy_cli/test_max_ops_per_batch.py +++ b/tests/comfy_cli/test_max_ops_per_batch.py @@ -253,8 +253,14 @@ def test_the_batch_bound_binds_only_far_past_any_real_workflow(): the absolute upper bound on nodes+links is 212, still a fifth of the bound. The largest expressible workflow in this repo's own fixtures mints 3 ops. - This test pins the fixture end of that measurement, which is the half that - can regress in CI. + What that measurement does NOT cover is the ``old`` side. ``replace_ops`` + emits a ``delete_node`` per node already in the document being replaced, and + that document is user data bounded by nothing here — see + ``test_the_old_document_counts_toward_the_batch_too``. Both production + callers degrade rather than fail on it. + + This test pins the fixture end of the ``new``-side measurement, which is the + half that can regress in CI. """ fixture = json.loads((_FIXTURES / "seedream_5_0_pro_t2i_ui.json").read_text(encoding="utf-8")) minted = ops.replace_ops({"nodes": [], "links": []}, fixture) From 82f2405c545ffb36113140137811be096297f51b Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 07:43:08 +0000 Subject: [PATCH 23/30] =?UTF-8?q?docs(op-vocabulary):=20count=20the=20six?= =?UTF-8?q?=20corrections=20=C2=A722=20carries,=20not=20five?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §22's preamble was written when the amendment held five subsections and was not updated as the sixth landed, so the section announced a count its own body contradicted. The six are 22.1-22.6; nothing else changes. --- docs/op-vocabulary-v1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index 26e5a6f5a..e05645041 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1473,7 +1473,7 @@ this document by SHA move the SHA together with their comfy-cli pin. ## 22. Amendment v1.13 — 2026-10-31 (v1.11 corrections: canonical form and ledger edges) -Five corrections to Amendment v1.11, all found by review of the implementation +Six corrections to Amendment v1.11, all found by review of the implementation rather than by a failure in the field. None of them re-scopes an op kind and none needs a change in `comfy-multi-player`; each is comfy-cli coming into line with what v1.11 and CMP A8 already say. From 4196a32c9e3cea799fcb8a124d86756a85720860 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 07:46:34 +0000 Subject: [PATCH 24/30] docs(op-vocabulary): say which refusal the charge-site check can change MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §22.2 claimed charging at the charge site "changes no outcome". That is true of WHETHER a payload is refused and not of WHICH code it is refused with, and the difference is observable: an object carrying both an oversized key and a value nested past the depth limit reported `payload_too_deep:` before this change and reports the cost budget after it, because the key is now charged and checked before the values are reached. Measured both ways on this branch and on its parent. Both are refusals of the same payload and no single-violation payload changes its code, so nothing a caller classifies on moves — but a document downstream repos pin by SHA should not overstate it. --- docs/op-vocabulary-v1.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index e05645041..ec889a0df 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1529,11 +1529,21 @@ input — so an oversized string, or an oversized object key at the `+= len(name charge, was fully rendered before being refused. The bound therefore did not bound the work. -Charging and refusing at the same point fixes that and changes no outcome, -because the budget only ever grows: every payload that exceeded at the end -exceeds at the charge that crossed the line. The shared package already has this -property for the same reason — `opBoundsRefusal` walks and charges the payload -before `normalize` renders anything. +Charging and refusing at the same point fixes that, and it does not change +WHETHER a payload is refused, because the budget only ever grows: every payload +that exceeded at the end exceeds at the charge that crossed the line, and every +charge that crosses the line is followed by an end that is also over. The shared +package already has this property for the same reason — `opBoundsRefusal` walks +and charges the payload before `normalize` renders anything. + +What it can change is WHICH refusal a payload that breaks two bounds at once +reports. An object with an oversized key AND a value nested past the depth limit +used to charge every key without checking, reach the values, and report +`payload_too_deep:`; it now reports the cost budget at the key. Both are +refusals of the same payload, and the cost-first order is the one CMP's +depth-first walk already produces, so this moves comfy-cli toward the +counterpart rather than away from it. No single-violation payload changes its +code. ### 22.3 Object keys that collide after coercion are `malformed_op` From 90f0a2757d5da28d54434e6b9cf631b2724dad88 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Sat, 31 Oct 2026 08:49:22 +0000 Subject: [PATCH 25/30] ci(hygiene): allowlist IEEE-754, the floating-point standard `public-repo-hygiene` failed on this branch with three findings, all the same token: `IEEE-754` in `comfy_cli/workflow_ops.py`, `docs/op-vocabulary-v1.md` and `tests/comfy_cli/test_op_id_reuse_contract.py`. It is the IEEE floating-point standard, named while documenting why an integer past 2^53 is spelled the way ECMAScript spells it, and it matches the checker's deliberately generic `\b[A-Z]{2,6}-\d{2,6}\b` ticket shape. The upstream checker already treats public standards identifiers as a known false-positive class: `UTF-8`, `ISO-8601`, `SHA-256` and three `RFC-####`s are exact-token entries, and `CVE`/`CWE`/`PEP`/`RFC`/`ISO`/`UTF` are prefix carve-outs. `IEEE` is on neither list yet. Only the exact-token list is reachable from a caller, so this adds the token here; the namespace carve-out belongs upstream in `TICKET_ALLOWED_PREFIXES`. Verified against the pinned checker (`github-workflows@3b2c8ca`) on this head: 3 findings before, exit 0 and "no internal-only references found" after, with no other finding appearing or disappearing. --- .github/workflows/public-repo-hygiene.yml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/workflows/public-repo-hygiene.yml b/.github/workflows/public-repo-hygiene.yml index 196f61dda..d6b720fbb 100644 --- a/.github/workflows/public-repo-hygiene.yml +++ b/.github/workflows/public-repo-hygiene.yml @@ -40,7 +40,19 @@ jobs: # set_title prototype that ADR-032 originally recorded, since # generalized and merged there as PR #235). It fits the ticket-ID shape # but is a public doc filename, not an internal ticket. - ticket_allowlist: HAILUO-03,HALO-03,ADR-032 + # `IEEE-754` is the IEEE floating-point standard, named in + # comfy_cli/workflow_ops.py, docs/op-vocabulary-v1.md and + # tests/comfy_cli/test_op_id_reuse_contract.py while documenting why an + # integer past 2^53 is spelled the way ECMAScript spells it. The checker + # already carries `UTF-8`, `ISO-8601`, `SHA-256` and three `RFC-####`s as + # exact tokens and `CVE`/`CWE`/`PEP`/`RFC`/`ISO`/`UTF` as prefixes, so a + # public standards identifier is a known class of false positive there; + # `IEEE` is simply not on either list yet. Only the exact-token list is + # reachable from a caller, so this is the token, not the namespace — a + # prefix carve-out for `IEEE` belongs upstream in + # TICKET_ALLOWED_PREFIXES, where the same comment already argues the + # namespace is the right granularity for this class. + ticket_allowlist: HAILUO-03,HALO-03,ADR-032,IEEE-754 # One `exclude_paths:` entry, and the bar it had to clear is recorded here # because the entry is permanent. Every entry this caller used to carry # was a false positive in the checker itself — Hugging Face model URLs and From ce6ecc876686a7a2cff310f20fda06d9a58a5bb9 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Sat, 31 Oct 2026 09:36:18 +0000 Subject: [PATCH 26/30] test(workflow): stop asserting a seeded empty ledger on a rejected op MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Amendment v1.11 (op-vocabulary-v1.md §20.2, landed via #1091) made a non-insert op carrying `definitions` raise before `_applied_ops` is seeded, so a document that arrived without a ledger is never left carrying an empty one by a rejection. This pre-existing test still asserted the old seeded-ledger shape and was failing CI on the exact head (90f0a27) the amendment is part of; test_op_id_reuse_contract.py already covers the corrected contract for the same two raise sites. --- tests/comfy_cli/test_insert_workflow_op.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/comfy_cli/test_insert_workflow_op.py b/tests/comfy_cli/test_insert_workflow_op.py index c92148483..69c958468 100644 --- a/tests/comfy_cli/test_insert_workflow_op.py +++ b/tests/comfy_cli/test_insert_workflow_op.py @@ -186,4 +186,6 @@ def test_non_definition_op_rejects_definitions_field(): with pytest.raises(ValueError, match="malformed_op.*definitions"): workflow_ops.apply_op(live, op, None) - assert live == {"nodes": [], "links": [], "_applied_ops": []} + # Amendment v1.11 (op-vocabulary-v1.md §20.2): a document that arrived + # without a ledger is never left carrying an empty one by a rejected op. + assert live == {"nodes": [], "links": []} From cca91ef47f45a11ead42c260eba02439a3c915fd Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 11:30:51 +0000 Subject: [PATCH 27/30] docs(op-vocabulary): say generate degrades too, not that it raises MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §20.4's `replace_ops` bullet said `templates fetch --emit-ops` reports `ops_skipped` beside a file it still wrote "and `generate`'s emit path raises `EmitError`". That stopped being true in this PR: `write_frontend_workflow` catches `NotExpressibleError`, sets `ops_skipped` and still writes the file (`comfy_cli/command/generate/emit.py:679-694`), which is also what the headroom paragraph twelve lines further down already states ("Both callers degrade rather than fail on that case"). A normative document downstream repos pin by SHA carried both claims at once. Addresses https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4431095650 --- docs/op-vocabulary-v1.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/op-vocabulary-v1.md b/docs/op-vocabulary-v1.md index ec889a0df..57c2dcd2a 100644 --- a/docs/op-vocabulary-v1.md +++ b/docs/op-vocabulary-v1.md @@ -1438,11 +1438,11 @@ Where it is enforced, and the two different refusals: than the bound*, and *one op whose own payload is out of §20.3's bounds* — that last one because these ops are handed to a caller without ever passing through `apply_op`, so nothing else canonicalizes them. All three want the - same caller behaviour, which both production callers already implement — `templates fetch --emit-ops` reports - `ops_skipped` beside the file it still wrote, and `generate`'s emit path - raises `EmitError`. The count binds on the SUM of `old` and `new`, because - §8.8's replacement shape emits a `delete_node` per node already in `old` - before the adds. + same caller behaviour, which both production callers already implement — + `templates fetch --emit-ops` and `generate`'s emit path each report + `ops_skipped` beside the file they still wrote. The count binds on the SUM of + `old` and `new`, because §8.8's replacement shape emits a `delete_node` per + node already in `old` before the adds. Measured headroom, and what the measurement does NOT cover. Across all 735 workflows in `Comfy-Org/workflow_templates` — the gallery From dcb9bffdb19b9b0adbee09e2fb6d4541a9fd3ff3 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 11:31:04 +0000 Subject: [PATCH 28/30] test(workflow): drop the stale EmitError claim from a batch-bound docstring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `test_replace_ops_refuses_to_mint_one_op_past_the_limit` explained why the refusal is `NotExpressibleError` rather than a bare `ValueError` by contrasting the two callers: `templates fetch --emit-ops` non-fatal, "`generate`'s emit path turns it into an `EmitError`". This PR made `write_frontend_workflow` catch it and report `ops_skipped` beside the file it still writes, so both callers now behave the same way — which this file's own last docstring (`test_the_batch_bound_binds_only_far_past_any_real_workflow`) already says. The reason the test gives for the error class is unchanged and still correct: a bare `ValueError` would escape both handlers. Addresses https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4431095654 --- tests/comfy_cli/test_max_ops_per_batch.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/tests/comfy_cli/test_max_ops_per_batch.py b/tests/comfy_cli/test_max_ops_per_batch.py index 5abbb229e..d25ed7616 100644 --- a/tests/comfy_cli/test_max_ops_per_batch.py +++ b/tests/comfy_cli/test_max_ops_per_batch.py @@ -162,11 +162,10 @@ def test_replace_ops_refuses_to_mint_one_op_past_the_limit(): """Refused as ``NotExpressibleError``, not as a bare ``ValueError``. That is what the two production callers already catch, and the distinction is - behavioural rather than cosmetic: ``templates fetch --emit-ops`` treats it as - non-fatal and reports ``ops_skipped`` beside a file it has still written, - while ``generate``'s emit path turns it into an ``EmitError``. A bare - ``ValueError`` would escape both and crash a fetch that had otherwise - succeeded. + behavioural rather than cosmetic: both ``templates fetch --emit-ops`` and + ``generate``'s emit path treat it as non-fatal and report ``ops_skipped`` + beside a file they have still written. A bare ``ValueError`` would escape + both and crash a fetch that had otherwise succeeded. """ with pytest.raises(ops.NotExpressibleError, match=r"needs 1025 ops, more than the 1024-op batch limit"): ops.replace_ops({"nodes": [], "links": []}, _nodes(1025)) From 360f35a3547e63d5d1d23c1f3d41dd877b30d5e4 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 11:33:07 +0000 Subject: [PATCH 29/30] fix(generate): say in pretty mode that --emit-ops minted no batch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `--emit-ops` became non-fatal in this PR: when `replace_ops` cannot mint a legal batch the file is still written and the reason travels as `ops_skipped`. That key only reaches the JSON envelope, and `Renderer.emit` prints nothing in pretty mode, so a pretty-mode run that asked for ops and got none printed exactly what a successful one prints — "Wrote workflow" and the run hint — with nothing to tell the two apart. The condition is ordinary rather than exotic: a `delete_node` per node already at the target path is user data bounded by nothing, so emitting into a path that already holds a large workflow reaches it. A `renderer.warn` inside the existing `is_pretty()` branch, so JSON and NDJSON output is byte-identical; the hint names the fallback the envelope's consumer takes anyway (apply the file as a whole document). Two tests: the warning appears on a target already holding 1,025 nodes, and does not appear when the batch was minted. Both force `COMFY_OUTPUT=pretty`, because under CliRunner stdout is not a TTY and mode resolution would otherwise pick JSON and skip the branch. The first is red on the parent — pretty output carries only "Wrote workflow". Addresses https://github.com/Comfy-Org/comfy-cli/pull/1091#discussion_r4431095642 --- comfy_cli/command/generate/app.py | 11 +++ .../command/generate/test_emit_ops.py | 82 +++++++++++++++++++ 2 files changed, 93 insertions(+) diff --git a/comfy_cli/command/generate/app.py b/comfy_cli/command/generate/app.py index 642b7c438..a0d5fd412 100644 --- a/comfy_cli/command/generate/app.py +++ b/comfy_cli/command/generate/app.py @@ -684,6 +684,17 @@ def _track_error(error_kind: str, exc: BaseException) -> None: if renderer.is_pretty(): rprint(f"[bold green]Wrote workflow:[/bold green] {emit_path}") rprint(f" run it: comfy run --workflow {emit_path}") + if ops_skipped: + # `--emit-ops` is a request, and this is the one path where + # it silently went unanswered: the batch is reported as + # `ops_skipped` in the envelope below, which `emit()` does + # not print in pretty mode. Without this the user asked for + # ops, saw only "Wrote workflow", and had no way to tell the + # batch apart from one that was minted. + renderer.warn( + f"--emit-ops: no batch was minted — {ops_skipped}", + hint="the workflow file above is complete; apply it as a whole document", + ) payload = { "out": str(Path(emit_path).expanduser()), "model": name, diff --git a/tests/comfy_cli/command/generate/test_emit_ops.py b/tests/comfy_cli/command/generate/test_emit_ops.py index 79bee2489..1ff193a1d 100644 --- a/tests/comfy_cli/command/generate/test_emit_ops.py +++ b/tests/comfy_cli/command/generate/test_emit_ops.py @@ -472,6 +472,88 @@ def test_cli_emit_ops_writes_frontend_and_envelope_ops(tmp_path, monkeypatch, ru assert isinstance(on_disk.get("nodes"), list), "the written file is canvas-editable frontend format" +def test_cli_emit_ops_says_so_in_pretty_mode_when_no_batch_was_minted(tmp_path, monkeypatch): + """A skipped batch has to be visible to a human, not only to `--json`. + + `ops_skipped` travels in the envelope, and `Renderer.emit` prints nothing in + pretty mode — so a pretty-mode run that asked for `--emit-ops` and got no + batch printed exactly what a successful one prints ("Wrote workflow"), with + no way to tell the two apart. The condition here is the ordinary one: the + target path already holds a workflow large enough that the `delete_node` per + existing node pushes the batch past the 1,024-op bound. + """ + from typer.testing import CliRunner + + from comfy_cli.cmdline import app + + oi_path = tmp_path / "object_info.json" + oi_path.write_text(json.dumps(_object_info()), encoding="utf-8") + monkeypatch.setenv("COMFY_OBJECT_INFO_FILE", str(oi_path)) + out = tmp_path / "workflow.json" + out.write_text( + json.dumps( + { + "nodes": [ + {"id": i + 1, "type": "LoadImage", "widgets_values": ["example.png"], "inputs": [], "outputs": []} + for i in range(workflow_ops._MAX_OPS_PER_BATCH + 1) + ], + "links": [], + } + ), + encoding="utf-8", + ) + + # `COMFY_OUTPUT` rather than a TTY probe: under CliRunner stdout is not a + # TTY, so mode resolution (`Renderer.resolve` rule 6) picks JSON and the + # pretty branch under test is never reached. `NO_COLOR`/`COLUMNS` keep Rich + # from wrapping or styling the warning mid-assertion. + result = CliRunner().invoke( + app, + [ + "generate", + "nano-banana", + "--prompt", + "add sunglasses", + "--image", + "cat.png", + "--emit-workflow", + str(out), + "--emit-ops", + ], + env={"COMFY_OUTPUT": "pretty", "NO_COLOR": "1", "COLUMNS": "400"}, + ) + + assert result.exit_code == 0, result.output + assert "Wrote workflow" in result.output + assert "--emit-ops" in result.output and "no batch was minted" in result.output + assert "1024-op batch limit" in result.output + # The file is still the deliverable and is still the newly built graph. + on_disk = json.loads(out.read_text()) + assert len(on_disk["nodes"]) <= workflow_ops._MAX_OPS_PER_BATCH + + +def test_cli_emit_ops_is_quiet_in_pretty_mode_when_the_batch_was_minted(tmp_path, monkeypatch): + """The complement: the warning is conditional, not printed on every run.""" + from typer.testing import CliRunner + + from comfy_cli.cmdline import app + + oi_path = tmp_path / "object_info.json" + oi_path.write_text(json.dumps(_object_info()), encoding="utf-8") + monkeypatch.setenv("COMFY_OBJECT_INFO_FILE", str(oi_path)) + out = tmp_path / "workflow.json" + + result = CliRunner().invoke( + app, + ["generate", "nano-banana", "--prompt", "x", "--image", "cat.png", "--emit-workflow", str(out), "--emit-ops"], + env={"COMFY_OUTPUT": "pretty", "NO_COLOR": "1", "COLUMNS": "400"}, + ) + + assert result.exit_code == 0, result.output + assert "Wrote workflow" in result.output + assert "no batch was minted" not in result.output + + def test_cli_emit_ops_without_emit_workflow_is_an_error(tmp_path, monkeypatch): from typer.testing import CliRunner From 936d94909c7615e64c7ed60915542bbecb5d9038 Mon Sep 17 00:00:00 2001 From: bymyself Date: Sat, 31 Oct 2026 12:06:44 +0000 Subject: [PATCH 30/30] test(generate): pin the skipped-batch envelope, not only the pretty warning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit's two tests covered the writer and the pretty-mode warning but asserted nothing about the machine-readable half, which is the premise the warning exists for: `ops_skipped` reaches only the envelope, and `Renderer.emit` prints nothing in pretty mode. So the key the whole change rests on was untested on this path. Parametrized over `--json` and `--json-stream`, since the latter resolves to NDJSON and emits the same final envelope. Asserts the refusal reason is in `data.ops_skipped` and that `ops` is ABSENT rather than null or empty — the same envelope shape `templates fetch --emit-ops` uses, where a consumer branches on the key being there to decide whether to fall back to the whole-document path. Addresses the second-round nitpick on comfy_cli/command/generate/app.py:706-711. --- .../command/generate/test_emit_ops.py | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/tests/comfy_cli/command/generate/test_emit_ops.py b/tests/comfy_cli/command/generate/test_emit_ops.py index 1ff193a1d..bbdca0df7 100644 --- a/tests/comfy_cli/command/generate/test_emit_ops.py +++ b/tests/comfy_cli/command/generate/test_emit_ops.py @@ -532,6 +532,67 @@ def test_cli_emit_ops_says_so_in_pretty_mode_when_no_batch_was_minted(tmp_path, assert len(on_disk["nodes"]) <= workflow_ops._MAX_OPS_PER_BATCH +@pytest.mark.parametrize("flag", ["--json", "--json-stream"]) +def test_cli_emit_ops_reports_the_skip_in_the_machine_envelope(tmp_path, monkeypatch, flag): + """The machine-readable half of the same condition. + + The pretty warning exists because `ops_skipped` reaches only the envelope, + so that key is the whole premise and is worth pinning directly: on a skip the + envelope carries `ops_skipped` with the refusal reason and carries no `ops` + key at all, which is what lets a consumer fall back to the whole-document + path instead of inferring it from an empty batch. Both machine modes, since + `--json-stream` resolves to NDJSON and emits the same final envelope. + """ + from typer.testing import CliRunner + + from comfy_cli.cmdline import app + + oi_path = tmp_path / "object_info.json" + oi_path.write_text(json.dumps(_object_info()), encoding="utf-8") + monkeypatch.setenv("COMFY_OBJECT_INFO_FILE", str(oi_path)) + out = tmp_path / "workflow.json" + out.write_text( + json.dumps( + { + "nodes": [ + {"id": i + 1, "type": "LoadImage", "widgets_values": ["example.png"], "inputs": [], "outputs": []} + for i in range(workflow_ops._MAX_OPS_PER_BATCH + 1) + ], + "links": [], + } + ), + encoding="utf-8", + ) + + result = CliRunner().invoke( + app, + [ + flag, + "generate", + "nano-banana", + "--prompt", + "add sunglasses", + "--image", + "cat.png", + "--emit-workflow", + str(out), + "--emit-ops", + ], + ) + + assert result.exit_code == 0, result.output + envelope = json.loads(result.output.strip().splitlines()[-1]) + assert envelope["ok"] is True + data = envelope["data"] + assert "1024-op batch limit" in data["ops_skipped"] + # Absent, not null or empty: `templates fetch --emit-ops` uses the same + # envelope shape, and a consumer branches on the key being there. + assert "ops" not in data, sorted(data) + assert data["format"] == "frontend" + # The file is still written, which is the deliverable either way. + assert json.loads(out.read_text())["nodes"] + + def test_cli_emit_ops_is_quiet_in_pretty_mode_when_the_batch_was_minted(tmp_path, monkeypatch): """The complement: the warning is conditional, not printed on every run.""" from typer.testing import CliRunner