Skip to content
Closed
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
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
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
2 changes: 1 addition & 1 deletion docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ derives tree-wide IDs from `op_id`; producers submit raw IDs and do not inspect
## 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. 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. The round-trip suite also still needs coverage guards proving its optional metadata, definitions, slots, and widget features were exercised.
- **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 Down
23 changes: 11 additions & 12 deletions docs/adr/0001-op-based-crdt-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,9 @@ authority" is therefore not a design axis; the axes that matter are (a) applier
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.
14 changes: 10 additions & 4 deletions docs/api-contract-proposal.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,16 @@ Two halves:
- **Part 2 — open questions.** Not settled. This is what the meeting is for.
Each has a recommendation and the trade-off it costs.

Grounded against the source at `6793d75`, `docs/multiplayer-schema.md`, and the
op vocabulary in comfy-cli. Nothing on a default branch consumes this package
yet — the server doc host lives on an unmerged branch — so a contract change is
still cheap. That will not stay true.
Originally grounded against the source at `6793d75`,
`docs/multiplayer-schema.md`, and the op vocabulary in comfy-cli.
**Consumer-status correction, 2026-09-18:** the newer
[ADR-006](decisions/ADR-006-publish-to-npm-pin-exact-versions.md) records that
the frontend, cloud `services/agent/dochost` sidecar, and `examples/dochost`
consumed the published `0.1.0` package at its 2026-08-22 acceptance. Consumers
pin exact published versions and must be upgraded deliberately. The former
claim that no default-branch consumers existed and contract changes were cheap
is obsolete. This correction does not assert their current deployed versions
or revalidate every historical proposal below.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/decisions/ADR-001-single-shared-applier.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The deployed cloud architecture runs this TypeScript package in a stateless Node

`@comfyorg/comfy-multi-player` is the one implementation of op-to-document semantics.

- Browser and Node host consume the same package pinned by immutable git SHA.
- Browser and Node host consume the same package at the same exact published npm version (ADR-006).
- Do not add op-to-document logic in Go or another language.
- Keep applier, projection, and mint pure and portable, with `yjs` as the only runtime dependency.
- If a second implementation is ever unavoidable, record an invariant exception first and require shared golden-vector parity before use.
Expand Down
2 changes: 1 addition & 1 deletion docs/decisions/ADR-005-read-only-snapshot-surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ entrypoint: `readGraph`, `readMeta`, `docCatalogPin`, `hasNode`,
constant. Every entry maps to a demonstrated call site above; nothing was added
for symmetry.

The surface is enforced, not conventional. Four mechanical properties, each
The surface is enforced, not conventional. Five mechanical properties, each
proved by attempting the violation in `test/readonly-surface.test.ts`:

1. **No live handle escapes.** Nothing reachable from a return value is a
Expand Down
13 changes: 10 additions & 3 deletions docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,20 @@ stabilizing and no registry release existed. The package is now published to
npm as `@comfyorg/comfy-multi-player@0.1.0`, so consumers no longer need a git
checkout or an install-time `prepare` build.

At this decision's 2026-08-22 acceptance, `0.1.0` was the published release.
The repository manifest is currently version `0.2.1` with the
`GPL-3.0-only` license; this current-state note does not announce or perform a
new npm release.

All three consumers use the registry release: ComfyUI frontend, the cloud
`services/agent/dochost` sidecar on `main`, and the `examples/dochost` example
merged in PR #27. Git-SHA pinning has therefore been retired in practice.

## Decision

Publish `@comfyorg/comfy-multi-player` to the npm registry and have every
consumer pin an exact published version. The current shared version is `0.1.0`.
consumer pin an exact published version. At acceptance, the shared published
version was `0.1.0`; the repository manifest is currently `0.2.1`.

Version updates remain explicit, reviewable changes in each consumer. The
frontend, cloud doc-host, and examples MUST use the same exact package version
Expand All @@ -33,8 +39,9 @@ where they rely on identical applier behavior (ADR-001).
do not use version ranges for the shared applier.
- Publishing a new version is an explicit maintainer action with its own
cadence, separate from merging repository changes.
- Version `0.1.1` is pending to carry the package's license metadata after the
GPL-3.0 license change lands.
- The repository manifest and `LICENSE` now identify the package as
`GPL-3.0-only`; the earlier pending `0.1.1` license-metadata plan is historical
and no longer current.
- Consumers install the prebuilt registry artifact and no longer need to allow
this package's git-dependency `prepare` script.

Expand Down
Loading
Loading