Repository navigation
fix: verify checked-out package in isolated doc-host harness #214
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
christian-byrne
merged 7 commits into
main
from
christian-byrne/cmprec-43-dochost-harness
Sep 18, 2026
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
ef046d9
test: require executable-package identity and host parity
christian-byrne 978d0c9
fix: verify the checked-out package in isolated doc-host harness
christian-byrne ce7f63a
Merge remote-tracking branch 'origin/main' into christian-byrne/cmpre…
christian-byrne f61157b
test: satisfy Fallow for doc-host harness
christian-byrne 3fadb7e
test: expose rejected-batch delta mutations
christian-byrne d18aa73
fix: verify rejected doc-host batch delta
christian-byrne b5179cc
test: verify rejected operation stays out of applied ledger
christian-byrne File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,70 +1,73 @@ | ||
| # dochost CRDT POC harness | ||
| # Document-host package parity harness | ||
|
|
||
| A small **no-mock** harness that drives the **real** doc-host sidecar (from | ||
| `Comfy-Org/cloud`, `services/agent/dochost`) running the **real** applier in this package, | ||
| so you can watch a workflow document converge from ops + deltas without standing up the whole | ||
| cloud. It is a backend/protocol proof, **not** a live multiplayer demo. | ||
| This harness compares the checked-out CMP build with that exact package installed | ||
| in the real cloud document-host sidecar. It tests loopback HTTP and document | ||
| semantics, **not browser behavior or deployment readiness**. | ||
|
|
||
| > This example is a shareable way to exercise and reason about the V1 document-semantics path. | ||
| > It is not wired into CI. | ||
| ## Run | ||
|
|
||
| ## What is real vs. absent | ||
|
|
||
| | Piece | Here | Notes | | ||
| | --- | --- | --- | | ||
| | Applier / merge / projection / mint | **REAL** | this package (`@comfyorg/comfy-multi-player`) | | ||
| | doc-host sidecar server | **REAL** | `services/agent/dochost/src/server.ts` from cloud main | | ||
| | HTTP transport (mint/apply/project) | **REAL** | loopback `127.0.0.1:8095`, same as in-pod | | ||
| | Follower integration | **REAL** | a real `Y.Doc` fold of `snapshot + host deltas` (raw-struct fan-out) | | ||
| | Widget catalog / base graph / ops | **REAL fixtures + frozen op shapes** | `fixtures/catalog.json`, `fixtures/session-edit-heavy.session.jsonl` | | ||
| | Go agent, ingest relay, Redis, Postgres, Temporal, auth | **absent** | transport + persistence around the core, not doc semantics | | ||
| | Browser, `/ws` WebSocket, litegraph | **absent** | no FE doc-frame client exists yet | | ||
|
|
||
| The document-semantics path is 100% real; the networking + browser + persistence shell is | ||
| simply not part of this slice. Nothing is stubbed. | ||
|
|
||
| ## What it proves (all green) | ||
|
|
||
| 1. concurrent human `set_widget(seed)` and agent `add_node(CLIPTextEncode)+connect` both land; | ||
| 2. a follower that applied **only** the host's incremental Yjs deltas converges to the host | ||
| projection (raw-struct fan-out; convergence is projection-equality, per schema §2.5); | ||
| 3. redelivering a delta is a no-op (idempotency); | ||
| 4. deltas integrate order-independently at the follower. | ||
|
|
||
| ## Run it | ||
|
|
||
| You need a checkout of `Comfy-Org/cloud` main for the doc-host sidecar source at | ||
| `services/agent/dochost`. Then one command builds both halves, starts the sidecar, and drives it: | ||
| Use Node 22+ and a compatible checkout of `Comfy-Org/cloud` with | ||
| `services/agent/dochost`. Install this repository's development dependencies first: | ||
|
|
||
| ```bash | ||
| DOCHOST_SRC=/path/to/cloud-main/services/agent/dochost ./examples/dochost-poc/run.sh | ||
| # -> ALL GREEN: 7 passed, 0 failed | ||
| npm ci | ||
| DOCHOST_SRC=/path/to/cloud/services/agent/dochost ./examples/dochost-poc/run.sh | ||
| ``` | ||
|
|
||
| `services/agent/dochost/package.json` depends on the published npm-registry package | ||
| `@comfyorg/comfy-multi-player@0.1.0`, so its `npm ci` pulls the published applier. This harness's | ||
| fixtures come from the local build of this repo; `0.1.0` matches this repo at the publish point, | ||
| so the projection-equality check covers that local-build/published-package boundary. | ||
|
|
||
| Manual equivalent, if you'd rather not use the script: | ||
|
|
||
| ```bash | ||
| npm ci && npm run build # 1. build the applier (this repo) | ||
| ( cd "$DOCHOST_SRC" && npm ci && npm run build ) # 2. build the sidecar | ||
| # Yjs must be a SINGLE instance — a nested second copy breaks Yjs instanceof checks and makes | ||
| # project() throw "could not be cloned". npm ci dedupes; if you used a file: link, also: | ||
| rm -rf "$DOCHOST_SRC/node_modules/@comfyorg/comfy-multi-player/node_modules/yjs" | ||
| PORT=8095 node "$DOCHOST_SRC/dist/server.js" & # 3. start sidecar | ||
| node examples/dochost-poc/dochost-driver.mjs # 4. drive it (fixtures read from this repo) | ||
| The launcher builds and packs this checkout, prints the artifact SHA-256, and | ||
| copies the sidecar source into a disposable directory. All sidecar installation, | ||
| build and execution happen there. It installs the tarball over the sidecar's | ||
| registry dependency, verifies every installed `dist` file and the package manifest | ||
| against the tarball, verifies import resolution and one shared Yjs dependency, | ||
| then starts the sidecar. It never installs into or deletes dependencies from | ||
| `DOCHOST_SRC`. The temporary directory and child server are cleaned up on exit. | ||
|
|
||
| An incompatible sidecar fails at build or comparison; the launcher does not patch | ||
| the consumer or fall back to an older package. Version equality alone is not | ||
| artifact identity. Record both repositories' exact revisions and the printed | ||
| artifact digest when saving a test result. | ||
|
|
||
| ```diagram | ||
| Checked-out package ── pack ──► disposable sidecar ──► HTTP results | ||
| │ │ │ | ||
| │ one snapshot │ | ||
| │ │ │ | ||
| └──── direct apply ◄─────────┘ │ | ||
| └──── outcomes + projection compare ─┘ | ||
| ``` | ||
|
|
||
| Env: `DOC_HOST` (default `http://127.0.0.1:8095`), `CMP_PIN` (default = repo root, for fixtures), | ||
| `PORT` (default `8095`). | ||
|
|
||
| ## What it is NOT | ||
|
|
||
| Not a live multiplayer session and not something your laptop can join over the network. A true | ||
| "team connects to the graph and watches the agent edit" demo additionally needs: an FE `/ws` | ||
| doc-frame client + Follower `Y.Doc` + litegraph bridge (none on any branch yet); the Go agent + | ||
| ingest relay + Redis actually running; and a network-reachable endpoint. Those are where the | ||
| integration risk now lives. | ||
| ## Checks and limits | ||
|
|
||
| - A human seed edit and an agent node-plus-link batch both apply, with their | ||
| actual graph effects checked independently of result parity. | ||
| - Each ordered `ApplyResult` matches the direct build: operation identity, | ||
| outcome, stable rejection code and `ops_seen`. Human-readable error prose is | ||
| deliberately excluded. Legacy-only result shapes fail. | ||
| - Projections match after each batch. A real unknown-widget refusal aborts a | ||
| valid trailing operation; folding its returned delta must leave encoded state | ||
| byte-identical and must not record the trailing operation in `__applied`. | ||
| - Followers consuming only host deltas converge; duplicate and reversed delta | ||
| delivery preserve the projection. | ||
|
|
||
| All direct comparisons fork from the **same server-minted snapshot** and prior | ||
| host deltas. Direct-comparison updates never enter the host or follower stream | ||
| (KA-10, KA-6, FC-1). There is one shared applier implementation (KA-3/FC-3). | ||
| Object key order is immaterial; outcome and array order remain significant. | ||
| See [the invariants](../../docs/INVARIANTS.md). | ||
|
|
||
| `PORT` defaults to `8095`; the launcher refuses an already healthy service on that | ||
| port. When invoking the driver alone, `DOC_HOST` selects the HTTP endpoint and | ||
| `CMP_PIN` selects the local checkout containing fixtures, `dist` and dependencies. | ||
| **A driver-only run does not verify the server's installed artifact identity.** | ||
|
|
||
| The real sidecar run is manual, not part of CI. Automated harness regressions use | ||
| explicit launcher fakes and a small HTTP fixture; their results are not real | ||
| cloud acceptance evidence. No browser, canvas, WebSocket, agent turn loop, | ||
| authentication or persistence is exercised. Browser-visible changes still need | ||
| separate consumer QA. This example makes no claim about which frontend clients | ||
| exist on other branches. | ||
|
|
||
| Glossary: CMP = the standalone `@comfyorg/comfy-multi-player` package; | ||
| sidecar = cloud's Node document host; parity = matching results across execution | ||
| paths; artifact = the package tarball; snapshot = shared initial Yjs document | ||
| bytes; QA = quality assurance; CI = automated repository checks. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.