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
7 changes: 7 additions & 0 deletions packages/comfy-multi-player/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,13 @@ All notable changes to `@comfyorg/comfy-multi-player` are documented in this fil
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
this package uses semantic versioning.

## Unreleased

### Added

- Added the standalone `insert_workflow` op with deterministic, collision-safe
whole-tree id remapping keyed by the operation envelope id.

## 0.2.0 - 2026-08-30

### Changed
Expand Down
20 changes: 17 additions & 3 deletions packages/comfy-multi-player/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ Every op carries the same envelope, minted by its creator before dispatch:
}
```

Six kinds, frozen:
Eight kinds, frozen:

| Kind | Payload beyond the envelope | Batchable (authoring) |
|---|---|---|
Expand All @@ -345,6 +345,7 @@ Six kinds, frozen:
| `set_widget` | `node_id`, `widget` (name, never index), `value`, optional `old`; an interior write adds `path` AND `inner_widget` together (`InteriorSetWidgetOp`); a promoted HOST write adds `promoted: {value_index, instance_path, host_widgets_values}` instead — a positional write into a subgraph instance's opaque array (schema Amendment A15) | yes |
| `delete_node` | `node_id`, `removed_links` | yes |
| `clear` | `removed_nodes` | no |
| `insert_workflow` | `workflow` containing required `nodes` and optional `links`, `groups`, and `definitions`; minters submit raw ids and the applier remaps them | no |
| `reset_doc` | see [open questions](docs/api-contract-proposal.md) — currently rejected `op_deferred` by this package | no |

`FROZEN_OPS`, `DEFERRED_OPS`, and `BATCHABLE_OPS` are exported so you can check
Expand All @@ -355,7 +356,20 @@ Compile-time assertions in `src/types.ts` pin that `FROZEN_OPS` is exactly
is exactly `WireOp["op"]`, and that `BATCHABLE_OPS ⊆ FROZEN_OPS`, so the lists
and the unions cannot drift apart silently.

**`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the six kinds it
For `insert_workflow`, submit raw node, link, group, and definition ids without
inspecting document state. The applier owns deterministic, tree-wide remapping;
each derived id incorporates the envelope `op_id`, graph scope, id kind, and
original id. Numeric and string aliases with the same normalized id refer to
the same node, including in link endpoints. Definition ids are scoped to their
containing graph, so repeated nested ids in separate branches derive distinct
ids. A remapped definition id that collides anywhere in the stored
definition tree rejects the operation with `definition_conflict`. Duplicate or
missing raw ids reject it atomically with `malformed_op` at every definition
depth. Links with a missing origin or target node are dropped individually at
every depth, while valid sibling links remain. Private keys beginning with
`__` are recursively removed and never appear in the projected workflow.

**`Op` vs `WireOp`.** `Op` is what `applyOps` implements — the eight kinds it
can actually apply. `WireOp` is `Op` plus the deferred kinds a conforming peer
may legally put on the wire, and it is what `ApplyFailure.op` and the stamp
helpers take: a rejected `reset_doc` really does land in `failed.op`, so typing
Expand Down Expand Up @@ -410,7 +424,7 @@ implementation to replay it with no failures. If you are building a submission
surface in front of the applier, that admission layer is where `BATCHABLE_OPS`
belongs. `test/batch-policy.test.ts` pins all of this.

The normative definition of the op envelope and the six kinds is
The normative definition of the op envelope and eight kinds is
`docs/op-vocabulary-v1.md` in
[comfy-cli](https://github.com/Comfy-Org/comfy-cli), which mints these ops on
the agent side. The `Op` types here mirror those minted shapes field for field;
Expand Down
4 changes: 2 additions & 2 deletions packages/comfy-multi-player/docs/INVARIANTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ This is the machine-addressable review log for the package. IDs are stable; do n

**Amendment A9 closes three residual write-order holes:** values that clone but cannot be stored by Yjs are refused before `set_widget`, grow, and `add_node` writes; `connect.link_id` must satisfy both Y.Map-value and Y.Array-item domains; and non-iterable `delete_node.removed_links` is refused before the A7 node-presence gate or deletion. **Amendment A10 closes the reference-cycle hole and corrects the shallow write predicate from storability to encodability:** `applyOps` rejects cycles at A8's whole-op depth gate, while the write-site cycle guard independently protects `mint`; top-level `Date` values are refused at the write gate, and `mint` refuses out-of-int64 `BigInt` values because Yjs accepts but does not faithfully encode them. **Amendment A13 classifies every BigInt in an op envelope as `malformed_op` during A8's op-only canonicalization precondition, names its payload path, and therefore rejects before any document write or `op_id` record.** **Amendment A14 shape-validates `connect.link_type` as a string in the op-only precondition, before destination delete-wins or any write; arbitrary and unknown strings remain legal because this is not catalogue membership validation.** **Amendment A11 bounds the remaining breadth and size attack surface:** batches are capped before processing, while A8's whole-envelope canonicalization now caps collection entries and an approximate cost covering strings, keys, binary bytes, containers, and leaves.

The *rejection* half — "a rejected op leaves the doc untouched", stated in the `applyOps` module docstring in `src/applier.ts` and repeated as contract D4 — is swept table-driven in `test/ka4-rejection-byte-identity.test.ts`, one row per reachable rejection code across `add_node`, `set_widget`, `connect`, `connect`+grow, `delete_node`, `clear`, `reset_doc` and the envelope gate, asserting byte-identical `encodeStateAsUpdate` *and* that the `op_id` was not consumed. Completeness is enforced rather than asserted: one test compares the covered codes against `ALL_REJECTION_CODES`, and a second greps `src/applier.ts` for every `new OpRejectedError("…")` so a new code cannot be added without a row. **The four `connect` rejections this used to except are fixed (#34)** and are now ordinary rows in that sweep, asserting byte-identity and `op_id`-preservation like every other code; the block that deliberately asserted the bug is deleted and `KNOWN_KA4_VIOLATIONS` is kept empty so a regression has somewhere to be recorded.
The *rejection* half — "a rejected op leaves the doc untouched", stated in the `applyOps` module docstring in `src/applier.ts` and repeated as contract D4 — is swept table-driven in `test/ka4-rejection-byte-identity.test.ts`, one row per reachable rejection code across `add_node`, `insert_workflow`, `set_widget`, `connect`, `connect`+grow, `delete_node`, `clear`, `reset_doc` and the envelope gate, asserting byte-identical `encodeStateAsUpdate` *and* that the `op_id` was not consumed. Completeness is enforced rather than asserted: one test compares the covered codes against `ALL_REJECTION_CODES`, and a second greps `src/applier.ts` for every `new OpRejectedError("…")` so a new code cannot be added without a row. `insert_workflow` adds collision refusals for nodes and links; both validate before any write. **The four `connect` rejections this used to except are fixed (#34)** and are now ordinary rows in that sweep, asserting byte-identity and `op_id`-preservation like every other code; the block that deliberately asserted the bug is deleted and `KNOWN_KA4_VIOLATIONS` is kept empty so a regression has somewhere to be recorded.

### KA-5 — IDs are collision-free without coordination
**Rule:** Use 53-bit random mint; document high-water marks are advisory, never allocators; FE stable IDs must be non-colliding strings.
**Why:** Offline peers must create entities without a central allocator.
**Enforced by:** **UNGUARDED — see roadmap**.
**Enforced by:** `insert_workflow` derives scoped node, link, group, and definition ids from the immutable op envelope id plus each original id. It never reads high-water marks or current document state to allocate, so distinct operations remain collision-free and order-independent. General producer randomness remains **UNGUARDED — see roadmap**.

### KA-6 — Raw struct updates flow host → follower one-way only
**Rule:** Followers never write the shared doc.
Expand Down
4 changes: 4 additions & 0 deletions packages/comfy-multi-player/docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@

V1 is an op-based Yjs document applier implemented once in the shared `@comfyorg/comfy-multi-player` TypeScript package. The frontend consumes its workspace source directly; the Node doc-host sidecar consumes an exact npm release built from that same source. Semantic ops are the replication unit; the widget catalog is sha256-pinned and fail-closed in the deployed architecture.

ADR-022 adds the seventh implemented kind, `insert_workflow`, for atomic template insertion. The

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick (P3): FROZEN_OPS, the README, and the package entrypoint count eight implemented kinds. This should say “eighth”; docs/multiplayer-schema.md:48 has the same stale “seventh” wording. Tracked with the stale PR-body claims in FE-2282.

applier deterministically remaps whole-tree ids from the operation id, so distinct inserts cannot
collide and exact replay derives the same ids.

## Guard gaps

- ~~**Positive purity assertion (#22):**~~ **CLOSED.** `scripts/check-purity.mjs` asserts directly that the declared and resolved production dependency roots are exactly `{yjs}`, and `scripts/check-import-graph.mjs` asserts the same per source module via `src-runtime-dep-is-yjs-only`. A cross-language parity guard is still only warranted if a second-language implementation is proposed; the preferred policy remains no second implementation (tracked in the separate bullet below).
Expand Down
8 changes: 8 additions & 0 deletions packages/comfy-multi-player/docs/api-contract-proposal.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,14 @@ still cheap. That will not stay true.

## Part 1 — decisions to ratify

### D0. Workflow templates insert as one standalone op

**Accepted by ADR-022.** `insert_workflow` requires `nodes`; `links`, `groups`, and `definitions`
are optional and default to empty. Producers send raw workflows. The applier remaps every carried
id and internal reference deterministically from the op envelope id plus the original id and graph
scope. Different ops therefore cannot collide or depend on arrival order, while exact replay derives
the same ids and is idempotent. The op is stamped and not batchable.

### D1. Widgets are addressed by name, not by position

**Proposal.** A node's widget values live in a map keyed by widget name. The
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# ADR-022: Atomic workflow-template insertion

- **Status:** Accepted
- **Date:** 2026-09-11
- **Decider:** Christian
- **Source:** ADR-T8, in-app-agent program TDD (Notion)

## Context

Agents and users need to insert a complete workflow template, including subgraph definitions,
without decomposing it into independently observable graph edits. Existing op shapes deliberately
reject definition-bearing payloads and cannot express that transaction safely.

## Decision

Add the non-batchable `insert_workflow` op. Its frozen envelope carries one authoritative `workflow`
with required top-level nodes and optional links, groups, and definitions. The applier remaps every
carried node, link, group, and nested-definition id to a deterministic string derived from the op
envelope id, graph scope, id kind, and original id. Producers emit the raw workflow unchanged.

Internal node/link references and definition-instance types are rewritten to those derived ids.
Distinct insert ops therefore cannot collide, even when they carry the same raw ids; exact replay
derives the same ids and is a byte-identical no-op through the existing `op_id` gate. The operation
is one Yjs transaction and is stamped as its own register.

## Consequences

- Template insertion is atomic at the semantic-op boundary and deterministic on replay.
- Producers do not inspect document state or remap ids.
- Definition interiors retain scoped graph namespaces, all derived from the op id.
- Existing op schemas remain closed to definitions.

## Invariants

This decision touches KA-1, KA-2, KA-3, KA-4, KA-5, FC-1, FC-3, and FC-4.

## Glossary

- **ADR-T8:** the accepted in-app-agent program technical design for workflow insertion.
- **Canonical projection:** stable, key-sorted JSON used as the definition-content identity.
- **Envelope id:** the immutable `op_id` carried by the semantic operation.
- **Producer:** the cloud or CLI caller that emits the raw workflow payload.
26 changes: 26 additions & 0 deletions packages/comfy-multi-player/docs/multiplayer-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,9 @@ Normative inputs, in precedence order:
`fixtures/` (the evidence: three replayable sessions, six LWW vectors, the
exported catalog, machine-captured findings). Every DECISION below cites
the spike finding that forced it.
3. **ADR-022 / ADR-T8** — the local decision and accepted in-app-agent program
TDD add `insert_workflow` as the seventh implemented op without moving the
pinned comfy-cli vocabulary.

---

Expand Down Expand Up @@ -2044,3 +2047,26 @@ separate input register still decides whether that identity may occupy the
requested destination; losing that gate leaves no tuple or dangling reference.
This adds an internal `__stamps` key, not a root-layout change, so
`SCHEMA_VERSION` remains 2.

---

## Amendment A19 — 2026-09-11 — atomic workflow-template insertion

ADR-022 adds the standalone-only `insert_workflow` op. Its payload is one
authoritative workflow containing required top-level `nodes` and optional
`links`, `groups`, and `definitions`. The applier deterministically remaps every
inserted id from the immutable `op_id`, graph scope, id kind, and original id,
then rewrites internal references. Producers emit raw payloads. Distinct ops
cannot collide; exact replay derives the same ids. Duplicate ids within one raw
payload remain collision errors. Malformed link tuples are `malformed_op`.

Definition ids and every nested definition-interior graph id are remapped in
scoped namespaces. Definition-instance `type` values are rewritten with them,
so a consumer definition id is never used as a live id and no live-definition
conflict path remains.

The whole merge occurs in one Yjs transaction and claims the
`("insert_workflow", op_id)` stamp target. Exact replay is stopped by the
existing applied-op gate and is byte-identical. This adds graph content but no
new root or node-map layout, so `SCHEMA_VERSION` remains 2. Other op payloads
remain closed to definition-bearing fields.
2 changes: 1 addition & 1 deletion packages/comfy-multi-player/scripts/check-import-graph.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ const root = process.env.IMPORT_GRAPH_ROOT || dirname(dirname(fileURLToPath(impo
* not one per change. See `.agents/checks/import-graph.md` and the config's own
* "NO includeOnly" comment.
*/
const MIN_MODULES = Number(process.env.IMPORT_GRAPH_MIN_MODULES ?? 10);
const MIN_MODULES = Number(process.env.IMPORT_GRAPH_MIN_MODULES ?? 11);

const cli = join(root, "node_modules", ".bin", "depcruise");
const run = spawnSync(cli, ["--output-type", "json", "src"], {
Expand Down
Loading
Loading