Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
293 changes: 287 additions & 6 deletions comfy_cli/workflow_ops.py

Large diffs are not rendered by default.

116 changes: 113 additions & 3 deletions docs/op-vocabulary-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -354,11 +354,15 @@ 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
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.11** (§20) 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`).
* `_applied_ops`, `_applied_op_digests` (and `_widget_stamps`) are apply-time
bookkeeping, stripped before serialization to disk (`strip_internal`).

## 3. Conflict rules

Expand Down Expand Up @@ -1290,3 +1294,109 @@ No operation kind is added or removed. `FROZEN_OPS`, `DEFERRED_OPS`, and
`BATCHABLE_OPS` are unchanged. Downstream consumers that move their pinned
vocabulary SHA to v1.10 must preserve `subgraph_reuse` conflict metadata even
though replay itself continues to insert `op.node` opaquely.

## 20. Amendment v1.11 — 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.

### 20.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). 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
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.

### 20.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.

### 20.3 Bounds

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
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.
1 change: 1 addition & 0 deletions tests/comfy_cli/command/test_workflow_edit.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
1 change: 1 addition & 0 deletions tests/comfy_cli/command/test_workflow_edit_legacy_proxy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
2 changes: 2 additions & 0 deletions tests/comfy_cli/command/test_workflow_edit_promoted.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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):
Expand Down
68 changes: 68 additions & 0 deletions tests/comfy_cli/test_dynamic_combo_other_option_widget.py
Original file line number Diff line number Diff line change
Expand Up @@ -565,3 +565,71 @@ 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.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(
"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


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"
Loading
Loading