Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
82de028
test: pin payload depth boundaries
christian-byrne Sep 18, 2026
b2341cc
fix(pins): disambiguate private repository 404s
christian-byrne Sep 18, 2026
d2710e4
fix(pins): require public visibility for definitive 404s
christian-byrne Sep 18, 2026
8a0db02
test: recover module-relative fixtures and vector count guard
christian-byrne Sep 18, 2026
8c3042f
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 18, 2026
80240d4
docs: reconcile preserved review findings
christian-byrne Sep 18, 2026
97de26d
docs: retain manual amendment provenance and remaining coverage gaps
christian-byrne Sep 18, 2026
0c5244d
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 18, 2026
20362ca
test: strengthen recovery assertions
christian-byrne Sep 18, 2026
3e5debb
test: preserve unrelated compiler diagnostic assertion
christian-byrne Sep 18, 2026
52f5537
docs: resolve retained review evidence gaps
christian-byrne Sep 18, 2026
8560865
test: complete remaining review recovery rows
christian-byrne Sep 18, 2026
9e90e64
test: retain npm validity checks and explain matrix counts
christian-byrne Sep 18, 2026
1dbd31a
docs: correct retained verification claims
christian-byrne Sep 18, 2026
941781c
test: scope promoted host operation IDs per test
christian-byrne Sep 18, 2026
3e6cd1e
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 18, 2026
5a03178
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne Sep 18, 2026
41e8ead
Merge origin/main release-retry recovery into private-pin branch
christian-byrne Sep 18, 2026
e5a346c
refactor: narrow Lamport counters without numeric assertions
christian-byrne Sep 18, 2026
1697f86
Merge recovered documentation into standalone acceptance candidate
christian-byrne Sep 18, 2026
40635b8
Merge explicit counter narrowing into standalone acceptance candidate
christian-byrne Sep 18, 2026
bdef855
fix: enforce KA-13 for exported module-level state
christian-byrne Sep 18, 2026
7d2c597
Merge commit '41e8eadde6ff9ec5be24ed44b269133dd9d4f51b' into christia…
christian-byrne Sep 18, 2026
9fbe668
test: reproduce frontend routing in standalone contributor instructions
christian-byrne Sep 18, 2026
8e065ab
Merge commit 'bdef85525085649e73976b3662eeab87e938c0b5' into christia…
christian-byrne Sep 18, 2026
3c7dfc1
fix: keep package development and issue routing standalone
christian-byrne Sep 18, 2026
d244945
docs: correct historical schema consumer routing
christian-byrne Sep 18, 2026
4352bd6
docs: pin the published install example exactly
christian-byrne Sep 18, 2026
3af3dc5
docs: separate server sequencing from creator Lamport counters
christian-byrne Sep 18, 2026
df6d3b4
docs: enumerate mutation report inconclusive outcomes
christian-byrne Sep 18, 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
10 changes: 7 additions & 3 deletions .agents/checks/catalog-pinning.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,11 @@ Apply .agents/checks/catalog-pinning.md (KA-12, FC-10). The widget catalog
(fixtures/catalog.json) is pinned by sha256 at mint; the golden conformance
corpus and lww-vectors are SHA-pinned and one-way. Flag any change that
edits a pinned fixture without a corresponding manifest/SHA update, cites
the catalog/vocabulary by a moving branch instead of a SHA, or would let the
corpus drift without being regenerated in CI (verify:corpus).
the catalog/vocabulary by a moving branch instead of a SHA, or bypasses
catalog-corpus-check=verify:corpus, the CI hash-verification gate. Preserve the
one-way-corpus-rule: expected outputs come from the pinned upstream generator
or explicitly documented manual fixtures, never from the applier under test.
Regeneration is a separate manual procedure; CI verifies the retained hashes.
```
<!-- /coderabbit-instructions -->

Expand All @@ -43,6 +46,7 @@ carries it in a folded scalar, where every space is a legal line break. This blo
audited against the code for [#80](https://github.com/Comfy-Org/comfy-multi-player/issues/80) and
verified without a wording change.

<!-- claim: sha256 :: .coderabbit.yaml -->
<!-- claim: catalog-corpus-check=verify:corpus :: .coderabbit.yaml -->
<!-- claim: one-way-corpus-rule :: .coderabbit.yaml -->

> Before reporting PASS for any check above, apply [vacuity.md](vacuity.md): P0 to every check, P1 to any guard this change adds, P10 to what that guard's test asserts on, P2 to any tool you ran, and P7 to any run you quote.
4 changes: 4 additions & 0 deletions .agents/checks/dep-secrets-scan.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,18 @@ Detect known CVEs in dependencies and leaked secrets. Applies to any change; esp

1. Probe tools: `npm --version`, `gitleaks version`. If neither is available, skip and report the install hints (`npm i -g npm`, gitleaks: https://github.com/gitleaks/gitleaks#installing). If only one is available, run it and note the other was skipped.
2. **Dependency audit** (npm):

```bash
npm audit --json; echo "npm audit exit: $?"
```

Do not suppress stderr or discard the exit status: `npm audit` exits non-zero when it finds advisories, but a non-zero exit with no parseable JSON means the tool itself failed — report that as an error, not a clean result. Map severity `critical`→critical, `high`→major, `moderate`→minor, `low`→nitpick. Report package, version, advisory title, CVE, and patched version.
3. **Secrets** (gitleaks):

```bash
gitleaks detect --no-banner --report-format json --report-path /tmp/gitleaks.json --source .; echo "gitleaks exit: $?"
```

`gitleaks` exits `1` when it finds secrets and `2` on execution error — never collapse these to a pass. If the run errors or the report cannot be parsed, report it as an indeterminate/failed scan, not "no issues found". All secret findings are critical. Report file/line, rule, a redacted match, and advise removal plus credential rotation.

## Repo-specific emphasis
Expand Down
4 changes: 2 additions & 2 deletions .agents/checks/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ The `src/**` `path_instructions` entry is an umbrella over every profile, so it
load-bearing sentence is this profile's mutate-before-throw rule, so the anchor for it lives here: if
the generated block loses that requirement, CI fails rather than the bot quietly stopping to ask for
it. The needle is space-free because the YAML carries it in a folded scalar. That block's content was
moved byte-for-byte from a hand-written config and has **not** been audited — it still cites issue
#10 as open, and #10 is closed; see
moved byte-for-byte from a hand-written config and has **not** been audited — it still cites
issue #10 as open, and #10 is closed; see
[#80](https://github.com/Comfy-Org/comfy-multi-player/issues/80).

<!-- claim: validate-before-mutate :: .coderabbit.yaml -->
Expand Down
4 changes: 2 additions & 2 deletions .agents/checks/eslint.strict.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,12 @@ const statelessRules = {
"no-restricted-syntax": [
"error",
{
selector: "Program > VariableDeclaration[kind='let'], Program > VariableDeclaration[kind='var']",
selector: ":matches(Program, Program > ExportNamedDeclaration) > VariableDeclaration[kind=/^(let|var)$/]",
message: "KA-13: no module-level let/var; caller-owned state only.",
},
{
selector:
"Program > VariableDeclaration > VariableDeclarator:not([id.name='documentTransactionTails']) > NewExpression[callee.type='Identifier'][callee.name=/^(Map|Set|WeakMap|WeakSet)$/]",
":matches(Program, Program > ExportNamedDeclaration) > VariableDeclaration > VariableDeclarator:not([id.name='documentTransactionTails']) > NewExpression[callee.type='Identifier'][callee.name=/^(Map|Set|WeakMap|WeakSet)$/]",
message: "KA-13: no module-level mutable collection except the documented Y.Doc-keyed admission queue; inject state through the caller.",
},
],
Expand Down
8 changes: 6 additions & 2 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,12 @@ reviews:
conformance corpus and lww-vectors are SHA-pinned and one-way. Flag any
change that edits a pinned fixture without a corresponding manifest/SHA
update, cites the catalog/vocabulary by a moving branch instead of a
SHA, or would let the corpus drift without being regenerated in CI
(verify:corpus).
SHA, or bypasses catalog-corpus-check=verify:corpus, the CI
hash-verification gate. Preserve the one-way-corpus-rule: expected
outputs come from the pinned upstream generator or explicitly
documented manual fixtures, never from the applier under test.
Regeneration is a separate manual procedure; CI verifies the retained
hashes.
- path: "scripts/**"
# source: .agents/checks/purity.md
instructions: >-
Expand Down
9 changes: 3 additions & 6 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
blank_issues_enabled: false
blank_issues_enabled: true
contact_links:
- name: Active package issues and questions
url: https://github.com/Comfy-Org/ComfyUI_frontend/issues/new/choose
about: Active development has moved to ComfyUI_frontend/packages/comfy-multi-player. Open all new work there.
- name: Security report
url: https://github.com/Comfy-Org/ComfyUI_frontend/security/advisories/new
about: Report security vulnerabilities privately in the canonical ComfyUI_frontend repository.
url: mailto:support@comfy.org
about: Report package vulnerabilities privately to Comfy support. Include the package name and affected version; do not open a public issue.
36 changes: 20 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -648,11 +648,14 @@ way.
Published to npm as [`@comfyorg/comfy-multi-player`](https://www.npmjs.com/package/@comfyorg/comfy-multi-player):

```bash
npm install @comfyorg/comfy-multi-player
npm install --save-exact @comfyorg/comfy-multi-player@0.2.1
```

The server pins an **exact** published version. The frontend consumes the
workspace source from the same commit that produces that release. Conflict
This is an exact published-version example, not a claim that unreleased main
changes are included. Coordinate version upgrades across consumers.

The server and frontend must pin the same **exact** published version. Package
development stays in the standalone repository; consumers do not vendor its source. 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 @@ -665,21 +668,22 @@ superseded) remains documented for historical context.
## Develop

```bash
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
npm ci
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
```

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.
The canonical writable source is
[`Comfy-Org/comfy-multi-player`](https://github.com/Comfy-Org/comfy-multi-player).
Run these commands from this repository's root. Target package code, tests, docs,
and release tooling at standalone `main`. Frontend adapters belong on frontend
`main`; the deferred frontend migration is not a development base.

`fixtures/` holds the replay corpus: recorded op sessions with their starting
and final workflows, six conflict-resolution vectors, and the pinned catalog.
Expand Down
16 changes: 13 additions & 3 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## Current state

V1 is an op-based Yjs document applier implemented once in the shared `@comfyorg/comfy-multi-player` TypeScript package. The browser and Node doc-host sidecar consume the same git-SHA-pinned package. Semantic ops are the replication unit; the widget catalog is sha256-pinned and fail-closed in the deployed architecture.
V1 is an op-based Yjs document applier implemented once in the shared `@comfyorg/comfy-multi-player` TypeScript package. The browser and Node doc-host sidecar must consume the same exact published npm version (ADR-006); merging recovery code does not publish it or update consumers. Semantic ops are the replication unit; the widget catalog is sha256-pinned and fail-closed in the deployed architecture.

ADR-031 adds the standalone-only `insert_workflow` kind for atomic template insertion. The applier
derives tree-wide IDs from `op_id`; producers submit raw IDs and do not inspect document state.

## 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).
- **Property tests (#24):** cover arbitrary op sequences, legal causal permutations, retries, batch boundaries, actor counts, byte-identical idempotency, and schema-version failure on the normal read path. Narrowed by #38: the normal read path now HAS a schema gate (`project()` → `assertReadableSchema`), enumerated case-by-case in `test/schema-version-on-read.test.ts`, and **KA-11** no longer points here for it. What remains open under #24 is the PROPERTY-based form — the enumerated cases are hand-written, not generated.
- **Property tests (#24):** **PARTIALLY CLOSED.** `test/pbt-convergence.test.ts` generates actor counts, legal causal permutations, retries, batch boundaries, convergence, and byte-identical double-apply idempotency. `test/pbt-mint-project-roundtrip.test.ts` generates workflows and op streams for mint/apply/project round trips and retry determinism, with witness guards for optional metadata, definitions, slots, and widget features. These are fixed-seed samples, not exhaustive coverage. The normal read-path schema gate is covered case-by-case, not property-based, in `test/schema-version-on-read.test.ts`; generated malformed/non-current schema layouts remain a gap.
- **Catalog-SHA lint (#22):** ~~fail on moving branch/tag citations in vocabulary and catalog references.~~ **Landed** as `scripts/check-pins.mjs` + `docs/upstream-pins.json` + `test/upstream-pins.test.ts`. Offline in CI; `npm run check:pins -- --verify-remote` additionally proves each pinned SHA still resolves upstream and each cited section still exists at it, and reports INCONCLUSIVE rather than passing when it cannot reach GitHub. Remaining, and the reason KA-12 keeps a scoped UNGUARDED marker: `meta.catalog_version`'s own sha256 shape is asserted by `test/catalog-sha-binding-integration.test.ts` but is not rejected at either write site — neither `mint()` (`src/mint.ts`) nor the module-private `initDoc()` helper (`src/doc.ts`) validates it, so `mint(workflow, catalog, "main")` still succeeds. That is Q4, not this lint.
- **Conformance-corpus provenance (#23):** record generator repository and commit SHA, command, environment, and manifest; regenerate and diff in CI.
- **Cross-language parity guard (#22):** if the single-package decision is deliberately revisited, both implementations must pass shared golden vectors before merge.
Expand All @@ -22,4 +22,14 @@ These are follow-up behavior/CI tickets. The remaining ones do not change op sem

## Repository plan

Completed by [ComfyUI_frontend #16644](https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644): active development and release ownership moved to `ComfyUI_frontend/packages/comfy-multi-player` after the V1 contract stabilized. This repository remains a read-only record of its standalone history, tags, and releases through 0.2.1. The package keeps the identical `@comfyorg/comfy-multi-player` import path; no second writable implementation remains here.
[Comfy-Org/comfy-multi-player](https://github.com/Comfy-Org/comfy-multi-player) is
the canonical writable source for package code, tests, documentation, and release
tooling. Target this repository's `main`; frontend adapters and consumers target
frontend `main` and pin the published package rather than relocating its source.

The migration proposed in
[ComfyUI_frontend #16644](https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644)
is closed and deferred, not completed. Preserve that PR and its descendant review
and QA records as recovery evidence, not as working branches or merge targets.
Future consolidation requires new explicit maintainer authorization; recovery
does not authorize package publication or deployment.
27 changes: 13 additions & 14 deletions docs/adr/0001-op-based-crdt-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,16 +33,16 @@ authority" is therefore not a design axis; the axes that matter are (a) applier
Bootstrap/reconnect uses one naive full seeded snapshot (acknowledged to need later iteration).
3. **Persist raw ops end-to-end (V1 target).** Store raw ops so the system is replayable; derive
ordering directly from the ops. The server-driven sequence number must NOT be the
conflict-resolution key — it may advance `base_version` but must never be the sole ordering
authority. (Today only an incrementing sequence pointer is persisted, so the system is not
conflict-resolution key and is independent of the creator-owned `base_version`
Lamport counter. (Today only an incrementing sequence pointer is persisted, so the system is not
replayable and all reconnection hinges on that counter; fixing it needs new tables. Ops are
small — data volume is not the blocker.)
4. **Persistence is separate from merge.** Every writer applies then writes; ensure no pending ops
before a write; never pull the DB as a higher authority (that collapses back to de-facto
full-document last-writer-wins).
5. **Defer the logical clock past V1.** A scalar `base_version` gives deterministic convergence for
V1; a vector/Lamport/HLC clock (faithful causality across long offline branches) is deferred and
requires op-sharing + replay first. See `src/types.ts` (`[base_version, actor, op_id]`) and
5. **Logical-clock decision superseded.** V1 originally deferred a logical clock. [ADR-0005](0005-lamport-ordering-v1-migration.md)
supersedes that choice: producers mint `base_version` as a durable, creator-owned Lamport counter,
while the total winner key remains `[base_version, actor, op_id]`. See `src/types.ts` and
`src/stamps.ts`.
6. **Applier stays a pure, portable package** with no client-idiosyncratic local state and no
DOM/framework/server-only deps, so it runs identically in browser and host (and a future peer).
Expand Down Expand Up @@ -96,11 +96,10 @@ flowchart LR
re-minted).
- **Ordering is independent of arrival order.** The canonical winner of two concurrent ops is
computed from the op stamp `[base_version, actor, op_id]`, which every replica evaluates
identically offline — never from receive order. `base_version` is a scalar version cursor the host
advances on apply, not a causal clock; `actor` and `op_id` are pure tie-breakers applied only
after it. The known limitation — a scalar cursor cannot faithfully represent causality across long
independent offline branches — is the deferred logical-clock item, out of V1 scope. Convergence
tests must deliver concurrent ops in both arrival orders and assert an identical winner.
identically offline — never from receive order. [ADR-0005](0005-lamport-ordering-v1-migration.md)
supersedes V1's scalar-cursor design: `base_version` is now a durable, creator-owned Lamport
counter; `actor` and `op_id` remain deterministic tie-breakers. Convergence tests must deliver
concurrent ops in both arrival orders and assert an identical winner.
- **Invalid-op batch semantics: valid-prefix commit, abort remainder.** Ops in a batch apply in
stamp order. The first invalid op aborts the remainder: the applied valid prefix is committed and
persisted, `base_version` advances only for committed ops, and the unprocessed suffix (from the
Expand Down Expand Up @@ -156,8 +155,8 @@ flowchart LR
- **Positive:** future peer-to-peer / LAN, hostless multiplayer on hosted or enterprise
deployments, multi-agent replay, offline and double-offline all remain reachable from the V1
shape. Ops give replay, observability, and cheap deltas.
- **Cost:** raw-ops persistence needs new DB tables; reconnect seeding is naive in V1; a proper
logical clock and conflict UX are deferred.
- **Cost:** raw-ops persistence needs new DB tables; reconnect seeding is naive in V1; conflict UX
is deferred. The original logical-clock deferral was superseded by ADR-0005.
- **Non-goals for V1:** vector clock, node-level conflict UX, separate-repo extraction of the
applier (the package boundary is kept, but extraction into a standalone repo is not required yet).

Expand All @@ -179,6 +178,6 @@ flowchart LR
- **Room host** — the server node process holding the in-memory Yjs doc for a workflow; a V1
convenience, not a conflict authority.
- **Headless peer** — the agent replica running with no browser attached.
- **base_version** — scalar version pointer; advances on apply. A V1 ordering aid, not the
permanent conflict key.
- **base_version** — the numeric element of the winner key; originally a V1 scalar version pointer,
now a durable, creator-owned Lamport counter under ADR-0005.
- **LWW** — last-writer-wins; here resolved by the op stamp, never by client-id or a DB read.
Loading
Loading