Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
b3f44e4
feat: support scoped interior connects
christian-byrne Sep 17, 2026
9b5583b
test: expose independent interior link arrival-order divergence
christian-byrne Sep 17, 2026
8419e16
fix: stabilize interior link addition order
christian-byrne Sep 17, 2026
d94aa21
test: pin prototype-named interior link order
christian-byrne Sep 17, 2026
36a2751
test: pin winning interior rewrite order across permutations
christian-byrne Sep 17, 2026
e9a1f6b
fix: persist canonical interior link ordering across replay
christian-byrne Sep 17, 2026
bcdf06a
wip: preserve definition recovery and pending review obligations
christian-byrne Sep 17, 2026
e1265e0
fix: preserve definition edits and satisfy carried review tests
christian-byrne Sep 17, 2026
18f905b
fix: canonicalize nested widget alias ownership
christian-byrne Sep 17, 2026
abcae34
fix(checks): recover inconclusive probe handling
christian-byrne Sep 17, 2026
b989d88
test: recover batch result helper contract
christian-byrne Sep 17, 2026
8b961df
fix(types): attach registry checks to OpKind
christian-byrne Sep 17, 2026
4b385cb
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
b97ada8
fix(checks): reject incomplete analyzer results
christian-byrne Sep 17, 2026
4a4c80a
test: preserve optional environment values in gate fixture
christian-byrne Sep 17, 2026
15c0443
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
7e6c54d
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
4e4f28a
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
1b3ae28
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
a1be1b0
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
5c51566
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 17, 2026
4482536
fix: retain definition edits across instance deletion
christian-byrne Sep 17, 2026
caa0107
feat: add insert_workflow op (ADR-022)
christian-byrne Sep 11, 2026
2f8798c
fix: recover op-id-derived workflow insertion
christian-byrne Sep 17, 2026
9778d4a
feat: recover first-class durable link lifecycle
christian-byrne Sep 17, 2026
0655881
merge: integrate standalone main into durable-link recovery
christian-byrne Sep 17, 2026
d2ee3c7
merge: combine standalone definitions insertion and durable links
christian-byrne Sep 17, 2026
dcbb117
test: preserve old-layout cases under schema-v3 refusal
christian-byrne Sep 17, 2026
6cbaac9
fix: preserve inserted link and definition identity
christian-byrne Sep 17, 2026
bfca299
test: reject malformed inserted links without partial writes
christian-byrne Sep 17, 2026
d9e3c1d
fix: validate inserted link descriptors before writes
christian-byrne Sep 17, 2026
1804f73
Merge remote-tracking branch 'origin/recovery-203' into christian-byr…
christian-byrne Sep 17, 2026
fc8eb5f
Merge remote-tracking branch 'origin/recovery-202' into christian-byr…
christian-byrne Sep 17, 2026
7886a6b
Merge remote-tracking branch 'origin/recovery-204' into christian-byr…
christian-byrne Sep 17, 2026
8bf867a
Merge remote-tracking branch 'origin/recovery-198' into christian-byr…
christian-byrne Sep 17, 2026
0760601
fix: adapt interior connect to canonical path resolution
christian-byrne Sep 17, 2026
48d9472
docs: align schema v3 contract guidance
christian-byrne Sep 17, 2026
78da245
fix: resolve retained interior connect routes
christian-byrne Sep 17, 2026
7db57f8
test: cover definition replication regressions
christian-byrne Sep 17, 2026
b51e92c
test: complete durable link lifecycle coverage
christian-byrne Sep 17, 2026
a462954
test: cover missing workflow insertion vectors
christian-byrne Sep 17, 2026
445694f
docs: clarify current schema and unsupported connect routes
christian-byrne Sep 17, 2026
47b0907
fix: preserve disconnected inputs during workflow insertion
christian-byrne Sep 17, 2026
b09dce0
fix: run stateless tools through Node entrypoints
christian-byrne Sep 17, 2026
19473b2
docs: reconcile recovered operation and schema contracts
christian-byrne Sep 17, 2026
5ee2c01
fix: direct old-layout readers to source re-minting
christian-byrne Sep 17, 2026
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
6 changes: 3 additions & 3 deletions .agents/checks/api-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ Catch breaking changes to this package's public surface. Applies to `src/index.t
2. **Op vocabulary** — op kind names, required fields, and the frozen/deferred sets are a contract shared with the server. Renaming an op kind, adding a required field to an existing op, or moving an op between frozen and deferred is breaking; cite the vocabulary section.
3. **Wire envelope** — the `{ type, data }` shape and `data.v` protocol version are cross-repo. Changing an existing message type, its payload shape, or bumping `data.v` without a documented migration is breaking.
4. **Stamp/order contract** — the total order key `[base_version, actor, op_id]` and `ApplyResult` shape (`applied`, `skipped`, `failed`, `version`) are consumed downstream; narrowing or reshaping them is breaking. **That field list is incomplete and known to be wrong — see "Known defects" below ([#73](https://github.com/Comfy-Org/comfy-multi-player/issues/73)); do not rely on it as an enumeration.**
In private alpha, `base_version` is the creator-owned Lamport counter carried in the single op format; there is no schema-v3 or dual-reader surface. DQ-11 incarnation-qualified target keys must remain unchanged.
5. **Schema/catalog versioning** — bump `SCHEMA_VERSION` when an old reader would mis-project a new doc, and keep a `migrate()` path (KA-11). Silently changing on-doc shape without a version bump is a breaking, fail-open change.
In private alpha, `base_version` is the creator-owned Lamport counter carried in the single op format. DQ-11 incarnation-qualified target keys must remain unchanged.
5. **Schema/catalog versioning** — bump `SCHEMA_VERSION` when an old reader would mis-project a new doc, and document an explicit old-layout disposition (KA-11). The current schema-v3 release refuses old layouts without mutation or relabelling, provides no compatibility reader, and re-mints source workflows. A future release must explicitly choose and document refusal, migration, or another disposition rather than universally promising migration support. Silently changing on-doc shape without a version bump is a breaking, fail-open change.
6. **Type narrowing / default changes** — an exported function that used to accept a wider input now rejecting part of it, or a changed default, can break callers.

## Rules

- Only flag changes that break existing consumers; do not flag additions.
- Check for a re-export alias or `migrate()` path before flagging.
- Check for a re-export alias and the documented old-layout disposition before flagging.
- Do not treat `__`-prefixed internal doc keys as public API.
- Critical for removed/renamed exports or op kinds; high for changed signatures or wire shapes; medium for changed defaults. Cite the affected KA-*/FC-* ID where relevant.

Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,15 @@ 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 for atomic workflow-template
insertion. The applier derives every carried node, link, group, and
definition ID from the operation ID and graph scope, avoiding allocation
against mutable document state.

## 0.2.0 - 2026-08-30

### Changed
Expand Down
83 changes: 53 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,12 +137,12 @@ unrecognized workflow key passed through untouched.
workflow content it throws `SchemaVersionError` when `meta.schema_version` is
absent, is not a positive integer, or is not this package's `SCHEMA_VERSION`. A document
NEWER than this package is refused rather than best-effort projected; a
document OLDER is refused too, and the message names the remedy — run
`migrate(doc, storedVersion)` on the **host** first, then read. `project()`
document OLDER is refused too. Re-mint an old document from its source workflow
with the current package; `migrate()` does not provide a compatibility reader.
`project()`
never migrates, because it is a read any replica may call — a browser follower
included — and a follower must not write the shared document (KA-6/FC-5). No
follower calls it today (the frontend does not depend on this package at all),
so this is a rule about the API, not an observation about callers.
included — and a follower must not write the shared document (KA-6/FC-5). This
is an API rule independent of which consumers currently call it.

This refusal is byte-exact: `encodeStateAsUpdate(doc)` and the `doc.share` key
set are both unchanged. It is also strictly *less* mutating than the old
Expand Down Expand Up @@ -170,18 +170,17 @@ the accept path.

### `migrate(doc, fromVersion): void`

Document-layout versioning, and the **migration path** a host runs before it
reads a document it did not mint. `SCHEMA_VERSION` is `1`, so today there is
nothing to step: the call validates and no-ops at v1, and throws
`SchemaVersionError` for everything else. A host never best-effort reads a
layout it does not know.
Document-layout version validation for the private-alpha current format.
`SCHEMA_VERSION` is `3`: the call validates and no-ops only at v3, and throws
`SchemaVersionError` for every older or newer layout without relabelling it.
Old layouts must be re-minted at their source; there is no compatibility reader.

`migrate()` is **no longer the only fail-closed read gate** — it was, and
nothing forced a caller through it, which is the fail-open gap #38 closed by
putting the same check inside `project()`. Both entrypoints share one
definition of the read (`readSchemaVersion`), so they agree on exactly which
documents are unreadable. `migrate()` remains **host-only**: followers receive
a migrated document over the struct stream or as a new epoch (schema §10).
a current-format document over the struct stream or as a new epoch (schema §10).

`fromVersion` is your *claim* about the document, and it is checked against the
document's own `meta.schema_version`. It throws when:
Expand Down Expand Up @@ -334,16 +333,18 @@ 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) |
|---|---|---|
| `add_node` | `node_id`, `class_type`, `pos`, `node` (the complete node object, inserted verbatim) | yes |
| `define_subgraph` | `subgraph_id`, `subgraph_definition` (the complete initial definition, inserted once) | yes |
| `connect` | `link_id`, `from_node`, `from_slot`, `to_node`, `link_type`, then EITHER a numeric `to_slot` (`ConcreteConnectOp`) OR a `grow` payload with `to_slot` null/absent (`GrowConnectOp`); `grow.promoted: true` names a subgraph instance's DECLARED input, materialized on the instance and LWW-gated as one register (schema Amendment A15) | yes |
| `disconnect` | `link_id`, `to_node`, `to_slot`; claims the same concrete input register as `connect` and removes the winning slot occupant | yes |
| `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 raw-ID `nodes` plus optional `links`, `groups`, and `definitions`; the applier remaps IDs deterministically from `op_id` | 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 @@ -354,7 +355,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 @@ -409,11 +423,14 @@ 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 historical op envelope and six-kind base vocabulary are defined by
`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;
a divergence is a bug here.
[comfy-cli](https://github.com/Comfy-Org/comfy-cli), with the adopted connect
amendment pinned separately below. The complete current eight-kind implemented
surface is defined locally by `src/types.ts` and
[`docs/multiplayer-schema.md`](docs/multiplayer-schema.md): `define_subgraph`
and ADR-031's standalone `insert_workflow` are local extensions, not claims
about the historical comfy-cli pin.

This package tracks that document at comfy-cli commit
`7e732242d971daf0d2d30f22f997abfacd78986e`, plus amendment v1.2 (§11) at
Expand Down Expand Up @@ -474,7 +491,7 @@ arrives on the update stream, not when the ack lists it as applied.

**Batches abort the remainder.** If op *k* fails, ops 0..*k*-1 stay applied and
ops *k*..*n* are not applied at all. Fix the failing op and resend the whole
batch with the **same** `op_id`s: the prefix comes back in `skipped`, the
batch with the **same** `op_id`s: the prefix comes back with `outcome: "no-op"`, the
remainder applies. Rejected ops consume no `op_id`, so a batch is retryable.

**The four `connect` rejections that used to break this are fixed (#34).**
Expand All @@ -491,8 +508,8 @@ Rejection codes: `malformed_op`, `unknown_op`, `op_deferred`,
`catalog_required`, `invalid_node_payload`, `unknown_widget`,
`uncatalogued_widget_write`, `opaque_widgets`, `widget_out_of_range`,
`input_slot_missing`, `output_slot_missing`, `not_a_subgraph`,
`interior_node_not_found`, `shared_definition_unforked`, and `apply_failed` for
anything unexpected. Match on `code`, never on `message`.
`interior_node_not_found`, `shared_definition_unforked`, `batch_aborted`, and
`apply_failed` for anything unexpected. Match on `code`, never on `message`.

`uncatalogued_widget_write` means a NAME-KEYED widget write named a class the
pinned catalog does not describe. `add_node` and `set_widget` (and `connect`'s
Expand Down Expand Up @@ -630,7 +647,8 @@ Published to npm as [`@comfyorg/comfy-multi-player`](https://www.npmjs.com/packa
npm install @comfyorg/comfy-multi-player
```

Pin an **exact** version in both the frontend and the server. Conflict
The server pins an **exact** published version. The frontend consumes the
workspace source from the same commit that produces that release. Conflict
resolution is a cross-process agreement about which write wins; two peers
running different versions of these rules can disagree about the outcome.

Expand All @@ -643,17 +661,22 @@ superseded) remains documented for historical context.
## Develop

```bash
npm install
npm run build # tsc → dist/
npm test # vitest: schema, purity, replay, lww, convergence, roundtrip, applier
npm run check:purity # dependency-tree + bare-Node import gate
npm run check:imports # module-graph gate: no cycles, src imports yjs only, no Node builtins
npm run check:pins # cross-repo citations are pinned by SHA, not a moving ref
npm run verify:corpus # conformance fixtures match their pinned SHAs
npm run check:profile-claims # .agents/checks prose still matches the code it restates
npm run check:coderabbit # .coderabbit.yaml still matches the profiles that generate it
pnpm install
pnpm run build # tsc → dist/
pnpm test # vitest: schema, purity, replay, lww, convergence, roundtrip, applier
pnpm run check:purity # dependency-tree + bare-Node import gate
pnpm run check:imports # module-graph gate: no cycles, src imports yjs only, no Node builtins
pnpm run check:pins # cross-repo citations are pinned by SHA, not a moving ref
pnpm run verify:corpus # conformance fixtures match their pinned SHAs
pnpm run check:profile-claims # .agents/checks prose still matches the code it restates
pnpm run check:coderabbit # .coderabbit.yaml still matches the profiles that generate it
```

The canonical source lives at
[`packages/comfy-multi-player`](https://github.com/Comfy-Org/ComfyUI_frontend/tree/main/packages/comfy-multi-player)
in the ComfyUI frontend workspace. Run these commands from that package directory,
or use `pnpm --filter @comfyorg/comfy-multi-player <command>` from the workspace root.

`fixtures/` holds the replay corpus: recorded op sessions with their starting
and final workflows, six conflict-resolution vectors, and the pinned catalog.
Format in [`fixtures/README.md`](fixtures/README.md). Add a fixture with any
Expand Down
Loading