From ef046d9165bcc115b06eb54449f1eca6816701b8 Mon Sep 17 00:00:00 2001 From: bymyself Date: Thu, 17 Sep 2026 21:26:43 -0700 Subject: [PATCH 1/6] test: require executable-package identity and host parity --- test/dochost-driver.test.ts | 121 ++++++++++++++++++++++++++++++++ test/portable-harness.test.ts | 128 +++++++++++++++++++++++++++++----- 2 files changed, 230 insertions(+), 19 deletions(-) create mode 100644 test/dochost-driver.test.ts diff --git a/test/dochost-driver.test.ts b/test/dochost-driver.test.ts new file mode 100644 index 0000000..d1b8587 --- /dev/null +++ b/test/dochost-driver.test.ts @@ -0,0 +1,121 @@ +import { createServer } from "node:http"; +import { spawn } from "node:child_process"; +import { mkdtempSync, rmSync, symlinkSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import * as Y from "yjs"; +import { applyOps, mint, project, type Op, type WidgetCatalog, type WorkflowJSON } from "../src/index.js"; + +type Body = Record; +const servers: ReturnType[] = []; + +async function run(mode = "match", packageRoot = resolve(".")) { + const requests: { path: string; body: Body }[] = []; + let applyNumber = 0; + const server = createServer(async (req, res) => { + const chunks: Buffer[] = []; + for await (const chunk of req) chunks.push(Buffer.from(chunk)); + const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) as Body : {}; + requests.push({ path: req.url!, body }); + res.setHeader("content-type", "application/json"); + if (req.url === "/health") return res.end('{"ok":true,"fixture":"loopback-not-cloud"}'); + if (req.url === "/mint") { + const doc = mint(body.workflow as WorkflowJSON, body.catalog as WidgetCatalog); + return res.end(JSON.stringify({ snapshot_b64: Buffer.from(Y.encodeStateAsUpdate(doc)).toString("base64") })); + } + const doc = new Y.Doc(); + Y.applyUpdate(doc, Buffer.from(body.snapshot_b64 as string, "base64")); + for (const update of body.updates_b64 as string[]) Y.applyUpdate(doc, Buffer.from(update, "base64")); + if (req.url === "/project") return res.end(JSON.stringify({ projection: project(doc, body.catalog as WidgetCatalog) })); + const before = Y.encodeStateVector(doc); + let apply_result: Body = applyOps(doc, body.ops as Op[], body.catalog as WidgetCatalog) as unknown as Body; + const projectionResult = project(doc, body.catalog as WidgetCatalog); + applyNumber++; + if (mode === "legacy" && applyNumber === 1) apply_result = { applied: [(body.ops as Op[])[0]!.op_id] }; + if (mode === "outcome" && applyNumber === 1) { + apply_result = structuredClone(apply_result); + (apply_result.outcomes as { outcome: string }[])[0]!.outcome = "no-op"; + } + if (mode === "order" && applyNumber === 2) { + apply_result = structuredClone(apply_result); + (apply_result.outcomes as unknown[]).reverse(); + } + if (mode === "count" && applyNumber === 1) apply_result = { ...apply_result, ops_seen: (apply_result.ops_seen as number) + 1 }; + if (mode === "reason" && applyNumber === 3) { + apply_result = structuredClone(apply_result); + ((apply_result.outcomes as Body[])[0]!.reason as Body).code = "different_code"; + ((apply_result.outcomes as Body[])[0]!.reason as Body).message = "message changes are deliberately ignored"; + } + if (mode === "message" && applyNumber === 3) { + apply_result = structuredClone(apply_result); + ((apply_result.outcomes as Body[])[0]!.reason as Body).message = "different volatile prose"; + } + const projection = mode === "projection" && applyNumber === 1 ? { ...projectionResult, extra: true } : projectionResult; + res.end(JSON.stringify({ apply_result, projection, update_b64: Buffer.from(Y.encodeStateAsUpdate(doc, before)).toString("base64") })); + }); + servers.push(server); + await new Promise((done) => server.listen(0, "127.0.0.1", done)); + const address = server.address(); + if (!address || typeof address === "string") throw new Error("missing loopback address"); + const child = spawn(process.execPath, [resolve("examples/dochost-poc/dochost-driver.mjs")], { + cwd: resolve("."), + env: { ...process.env, DOC_HOST: `http://127.0.0.1:${address.port}`, CMP_PIN: packageRoot }, + }); + let output = ""; + child.stdout.on("data", (chunk) => { output += chunk; }); + child.stderr.on("data", (chunk) => { output += chunk; }); + const code = await new Promise((done) => child.on("close", done)); + return { code, output, requests }; +} + +afterEach(async () => { + await Promise.all(servers.splice(0).map((server) => new Promise((done) => server.close(() => done())))); +}); + +describe("dochost driver executable-package oracle (tiny loopback fixture, not cloud)", () => { + it("matches outcomes/projections and forks every comparison from one bootstrap", async () => { + const result = await run(); + expect(result.code, result.output).toBe(0); + expect(result.requests.filter((request) => request.path === "/mint")).toHaveLength(1); + const applies = result.requests.filter((request) => request.path === "/apply"); + expect(applies).toHaveLength(3); + expect(applies.map(({ body }) => (body.updates_b64 as string[]).length)).toEqual([0, 1, 2]); + const hostUpdates = applies.map(({ body }) => body.updates_b64 as string[]).flat(); + expect(hostUpdates).toHaveLength(3); + expect(result.output).toContain("host: agent link present"); + }); + + it("ignores volatile rejection message prose", async () => { + const result = await run("message"); + expect(result.code, result.output).toBe(0); + }); + + it("imports the executable package from a path containing spaces and URL delimiters", async () => { + const directory = mkdtempSync(join(tmpdir(), "cmp-driver-")); + const checkout = join(directory, "checkout # with spaces"); + try { + symlinkSync(resolve("."), checkout, "dir"); + const result = await run("match", checkout); + expect(result.code, result.output).toBe(0); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }); + + it.each([ + ["outcome", "FAIL human ApplyResult matches local executable package"], + ["order", "FAIL agent ApplyResult matches local executable package"], + ["count", "FAIL human ApplyResult matches local executable package"], + ["reason", "FAIL rejected ApplyResult and stable reason code match local executable package"], + ["legacy", "sidecar returned legacy/invalid ApplyResult"], + ["projection", "FAIL human projection matches local executable package"], + ])( + "fails closed for %s drift even when other sidecar data matches", + async (mode, expectedFailure) => { + const result = await run(mode); + expect(result.code, result.output).toBe(1); + expect(result.output).toContain(expectedFailure); + }, + ); +}); diff --git a/test/portable-harness.test.ts b/test/portable-harness.test.ts index fb51898..0281ddd 100644 --- a/test/portable-harness.test.ts +++ b/test/portable-harness.test.ts @@ -1,5 +1,5 @@ import { spawn, spawnSync } from "node:child_process"; -import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { chmodSync, cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; @@ -15,11 +15,90 @@ function temp(prefix: string) { return path; } +function writeHarnessFakes(bin: string, healthy: boolean) { + writeFileSync( + join(bin, "npm"), + `#!/bin/bash +set -e +[ -z "\${HARNESS_NPM_LOG:-}" ] || printf '%s|%s\n' "$(pwd)" "$*" >> "$HARNESS_NPM_LOG" +if [ "$1" = pack ]; then + while [ "$1" != "--pack-destination" ]; do shift; done; dest="$2" + work="$(mktemp -d)"; mkdir -p "$work/package/dist" + printf "export const marker = 'packed';\\n" > "$work/package/dist/index.js" + printf '{"name":"@comfyorg/comfy-multi-player","version":"0.2.1","type":"module","exports":{".":{"import":"./dist/index.js"}},"dependencies":{"yjs":"*"}}' > "$work/package/package.json" + tar -czf "$dest/comfyorg-comfy-multi-player-0.2.1.tgz" -C "$work" package; rm -rf "$work" + printf '[{"filename":"comfyorg-comfy-multi-player-0.2.1.tgz"}]' +elif [ "$1" = install ]; then + tarball="\${!#}"; mkdir -p node_modules/@comfyorg/comfy-multi-player + tar -xzf "$tarball" -C node_modules/@comfyorg/comfy-multi-player --strip-components=1 +elif [ "$1" = ci ]; then + mkdir -p node_modules/yjs; printf '{"name":"yjs","main":"index.js"}' > node_modules/yjs/package.json; : > node_modules/yjs/index.js +elif [ "$1 $2" = "run build" ] && [ "$(pwd)" != "${repoRoot}" ]; then + mkdir -p dist; cat > dist/server.js <<'EOF' +import http from 'node:http'; +http.createServer((req,res) => { if (req.url === '/health') { res.end('ok'); } else { res.statusCode=404; res.end(); } }).listen(Number(process.env.PORT), '127.0.0.1'); +EOF +fi +`, + ); + writeFileSync(join(bin, "seq"), "#!/bin/sh\necho 1\n"); + writeFileSync(join(bin, "sleep"), "#!/bin/sh\nexit 0\n"); + writeFileSync( + join(bin, "curl"), + `#!/bin/sh +countfile="\${HARNESS_CURL_COUNT}"; count=0; [ ! -f "$countfile" ] || count=$(cat "$countfile"); count=$((count+1)); echo "$count" > "$countfile" +[ "$count" -gt 1 ] && exit ${healthy ? 0 : 1}; exit 1 +`, + ); + writeFileSync(join(bin, "node"), `#!/bin/sh\ncase "$1" in *dochost-driver.mjs) echo driver-ran;; *) exec "${process.execPath}" "$@";; esac\n`); + for (const executable of ["npm", "seq", "sleep", "curl", "node"]) chmodSync(join(bin, executable), 0o755); +} + afterEach(() => { for (const path of temporary.splice(0)) rmSync(path, { recursive: true, force: true }); }); describe("portable harness regressions", () => { + it("accepts an installed CMP whose complete dist tree matches the packed artifact", () => { + const root = temp("cmp-identity-"); + const packed = join(root, "packed/package"); + const stage = join(root, "stage"); + mkdirSync(join(packed, "dist/nested"), { recursive: true }); + writeFileSync(join(packed, "dist/index.js"), "export const marker = 'genuine';\n"); + writeFileSync(join(packed, "dist/nested/index.d.ts"), "export declare const marker: string;\n"); + writeFileSync(join(packed, "package.json"), '{"name":"@comfyorg/comfy-multi-player","version":"0.2.1"}'); + const installed = join(stage, "node_modules/@comfyorg/comfy-multi-player"); + mkdirSync(dirname(installed), { recursive: true }); + cpSync(packed, installed, { recursive: true }); + + const run = spawnSync(process.execPath, [join(repoRoot, "examples/dochost-poc/verify-package-identity.mjs"), packed, stage], { + encoding: "utf8", + }); + expect(run.status, run.stderr).toBe(0); + }); + + it.each(["dist bytes", "manifest"])("rejects same-version installed CMP with tampered %s", (tampered) => { + const root = temp("cmp-identity-tampered-"); + const packed = join(root, "packed/package"); + const stage = join(root, "stage"); + mkdirSync(join(packed, "dist"), { recursive: true }); + writeFileSync(join(packed, "dist/index.js"), "export const marker = 'genuine';\n"); + writeFileSync(join(packed, "package.json"), '{"name":"@comfyorg/comfy-multi-player","version":"0.2.1"}'); + const installed = join(stage, "node_modules/@comfyorg/comfy-multi-player"); + mkdirSync(join(installed, "dist"), { recursive: true }); + writeFileSync(join(installed, "dist/index.js"), tampered === "dist bytes" + ? "export const marker = 'stale';\n" : readFileSync(join(packed, "dist/index.js"))); + writeFileSync(join(installed, "package.json"), tampered === "manifest" + ? '{"name":"@comfyorg/comfy-multi-player","version":"0.2.1","exports":"./wrong.js"}' + : readFileSync(join(packed, "package.json"))); + + const run = spawnSync(process.execPath, [join(repoRoot, "examples/dochost-poc/verify-package-identity.mjs"), packed, stage], { + encoding: "utf8", + }); + expect(run.status).toBe(1); + expect(run.stderr).toContain("package identity mismatch"); + }); + it.each([ { name: "clean complete report", @@ -114,23 +193,32 @@ describe("portable harness regressions", () => { const sidecar = join(root, "sidecar"); mkdirSync(bin); mkdirSync(sidecar); - writeFileSync(join(bin, "npm"), "#!/bin/sh\nexit 0\n"); - writeFileSync(join(bin, "seq"), "#!/bin/sh\necho 1\n"); - writeFileSync(join(bin, "sleep"), "#!/bin/sh\nexit 0\n"); - writeFileSync(join(bin, "curl"), `#!/bin/sh\nexit ${healthy ? 0 : 1}\n`); - writeFileSync( - join(bin, "node"), - "#!/bin/sh\ncase \"$1\" in *dist/server.js) while :; do /bin/sleep 1; done;; *) echo driver-ran; exit 0;; esac\n", - ); - for (const executable of ["npm", "seq", "sleep", "curl", "node"]) - chmodSync(join(bin, executable), 0o755); + writeFileSync(join(sidecar, "package.json"), '{"name":"dochost","type":"module"}'); + writeFileSync(join(sidecar, "package-lock.json"), '{"name":"dochost","lockfileVersion":3,"packages":{"":{"name":"dochost"}}}'); + writeFileSync(join(sidecar, "source-marker"), "unchanged\n"); + writeHarnessFakes(bin, healthy); + const stages = join(root, "stages"); + mkdirSync(stages); + const npmLog = join(root, "npm.log"); const run = spawnSync("bash", [join(repoRoot, "examples/dochost-poc/run.sh")], { encoding: "utf8", - env: { ...process.env, PATH: `${bin}:/usr/bin:/bin`, DOCHOST_SRC: sidecar }, + env: { + ...process.env, + PATH: `${bin}:/usr/bin:/bin`, + DOCHOST_SRC: sidecar, + TMPDIR: stages, + HARNESS_CURL_COUNT: join(root, "curl-count"), + HARNESS_NPM_LOG: npmLog, + }, }); - expect(run.status).toBe(expectedStatus); + expect(run.status, run.stderr).toBe(expectedStatus); expect(run.stdout.includes("driver-ran")).toBe(healthy); if (!healthy) expect(run.stderr).toContain("sidecar did not become healthy"); + expect(readFileSync(join(sidecar, "source-marker"), "utf8")).toBe("unchanged\n"); + const docHostCommands = readFileSync(npmLog, "utf8").split("\n").filter((line) => /\|(ci|install|run build)/.test(line)); + expect(docHostCommands).not.toHaveLength(0); + expect(docHostCommands.every((line) => !line.startsWith(`${sidecar}|`))).toBe(true); + expect(readdirSync(stages)).toEqual([]); }); } @@ -140,11 +228,13 @@ describe("portable harness regressions", () => { const sidecar = join(root, "sidecar"); mkdirSync(bin); mkdirSync(sidecar); - writeFileSync(join(bin, "npm"), "#!/bin/sh\nexit 0\n"); - writeFileSync(join(bin, "seq"), "#!/bin/sh\necho 1\n"); - writeFileSync(join(bin, "sleep"), "#!/bin/sh\nexit 0\n"); - writeFileSync(join(bin, "node"), "#!/bin/sh\ncase \"$1\" in *dist/server.js) while :; do /bin/sleep 1; done;; *) exit 0;; esac\n"); - for (const executable of ["npm", "seq", "sleep", "node"]) chmodSync(join(bin, executable), 0o755); + writeFileSync(join(sidecar, "package.json"), '{"name":"dochost","type":"module"}'); + writeFileSync(join(sidecar, "package-lock.json"), '{"name":"dochost","lockfileVersion":3,"packages":{"":{"name":"dochost"}}}'); + writeHarnessFakes(bin, false); + // Exercise real curl's timeout; the staged child stays alive without binding + // this port, which is held by the deliberately stalled TCP server below. + rmSync(join(bin, "curl")); + writeFileSync(join(bin, "node"), `#!/bin/sh\ncase "$1" in dist/server.js) exec /bin/sleep 30;; *) exec "${process.execPath}" "$@";; esac\n`); const serverFile = join(root, "stall.mjs"); writeFileSync(serverFile, "import net from 'node:net'; net.createServer(() => {}).listen(0, '127.0.0.1', function () { console.log(this.address().port); });\n"); @@ -158,7 +248,7 @@ describe("portable harness regressions", () => { const run = spawnSync("bash", [join(repoRoot, "examples/dochost-poc/run.sh")], { encoding: "utf8", timeout: 2_000, - env: { ...process.env, PATH: `${bin}:/usr/bin:/bin`, DOCHOST_SRC: sidecar, PORT: port }, + env: { ...process.env, PATH: `${bin}:/usr/bin:/bin`, DOCHOST_SRC: sidecar, PORT: port, HARNESS_CURL_COUNT: join(root, "curl-count") }, }); expect(run.error).toBeUndefined(); expect(run.status).toBe(1); From 978d0c94c726d013463d9c337b3141f2ed05f60c Mon Sep 17 00:00:00 2001 From: bymyself Date: Thu, 17 Sep 2026 21:26:44 -0700 Subject: [PATCH 2/6] fix: verify the checked-out package in isolated doc-host harness --- examples/dochost-poc/README.md | 123 +++++++++--------- examples/dochost-poc/dochost-driver.mjs | 98 ++++++++++++-- examples/dochost-poc/run.sh | 69 ++++++++-- .../dochost-poc/verify-package-identity.mjs | 54 ++++++++ 4 files changed, 260 insertions(+), 84 deletions(-) create mode 100644 examples/dochost-poc/verify-package-identity.mjs diff --git a/examples/dochost-poc/README.md b/examples/dochost-poc/README.md index 421d330..dcd7674 100644 --- a/examples/dochost-poc/README.md +++ b/examples/dochost-poc/README.md @@ -1,70 +1,71 @@ -# 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, including a real unknown-widget refusal. +- 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. diff --git a/examples/dochost-poc/dochost-driver.mjs b/examples/dochost-poc/dochost-driver.mjs index 7e95d6b..3011f9b 100644 --- a/examples/dochost-poc/dochost-driver.mjs +++ b/examples/dochost-poc/dochost-driver.mjs @@ -1,14 +1,14 @@ /** * No-mock CRDT POC — drives the REAL doc-host sidecar from cloud main - * (services/agent/dochost/src/server.ts). The sidecar consumes the published - * @comfyorg/comfy-multi-player@0.1.0 package; this driver exercises that applier - * through the sidecar's HTTP contract. + * (services/agent/dochost/src/server.ts). run.sh installs the checked-out packed + * package in a disposable sidecar, verifies its identity, and invokes this + * driver to compare its HTTP results with the direct local build. * * Nothing here is stubbed: mint, apply, and project all execute inside the real * server over loopback HTTP; the follower is a real Y.Doc integrating only the * host's incremental Yjs deltas (raw-struct fan-out), never the whole doc. * - * Proves, end to end through the deployed server contract: + * Checks through the supplied sidecar's HTTP contract (not a deployment): * 1. concurrent human set_widget || agent add_node+connect both land; * 2. a follower that applied ONLY the host deltas converges to the host * projection (projection-equality, per schema §2.5 — state bytes differ by @@ -19,12 +19,16 @@ * Run: node examples/dochost-poc/dochost-driver.mjs (dochost must be on :8095) */ import { readFileSync } from "node:fs"; -import { fileURLToPath } from "node:url"; +import { fileURLToPath, pathToFileURL } from "node:url"; const HOST = process.env.DOC_HOST || "http://127.0.0.1:8095"; const CMP = process.env.CMP_PIN || fileURLToPath(new URL("../../", import.meta.url)); // repo root const catalog = JSON.parse(readFileSync(`${CMP}/fixtures/catalog.json`, "utf8")); +// Keep package-dependent imports below `const catalog =`: the launcher copies +// the source prefix to an artificial root as a portability regression probe. +const cmp = await import(pathToFileURL(`${CMP}/dist/index.js`).href); +const Y = await import(pathToFileURL(`${CMP}/node_modules/yjs/dist/yjs.mjs`).href); // Real base workflow: the team-spike edit-heavy session's base graph. const session = readFileSync(`${CMP}/fixtures/session-edit-heavy.session.jsonl`, "utf8") .split("\n") @@ -33,7 +37,6 @@ const session = readFileSync(`${CMP}/fixtures/session-edit-heavy.session.jsonl`, const base = session[0].base_workflow; const KSAMPLER = base.nodes.find((n) => n.type === "KSampler"); -const CLIP = base.nodes.find((n) => n.type === "CLIPTextEncode"); let idc = 0; const opId = () => (Date.now().toString(16) + (idc++).toString(16).padStart(4, "0")).padEnd(32, "0").slice(0, 32); @@ -44,13 +47,49 @@ async function post(path, body) { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), + signal: AbortSignal.timeout(10_000), }); const j = await r.json(); if (!r.ok) throw new Error(`${path} ${r.status}: ${JSON.stringify(j)}`); return j; } -const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b); +const canonical = (value) => { + if (Array.isArray(value)) return value.map(canonical); + if (value && typeof value === "object") { + return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])); + } + return value; +}; +const eq = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b)); +const stableOutcomes = (result) => { + if (!result || !Array.isArray(result.outcomes) || !Number.isInteger(result.ops_seen)) { + throw new Error(`sidecar returned legacy/invalid ApplyResult: ${JSON.stringify(result)}`); + } + return { + outcomes: result.outcomes.map((item) => ({ + op_id: item.op_id, + outcome: item.outcome, + ...(item.outcome === "rejected" ? { code: item.reason?.code } : {}), + })), + ops_seen: result.ops_seen, + }; +}; + +const directApply = (updates_b64, ops) => { + // KA-10: every direct comparison starts from the one server-minted bootstrap + // snapshot, then folds only prior HOST deltas. Its update is never sent to + // the host or followers. + const doc = new Y.Doc(); + try { + Y.applyUpdate(doc, Buffer.from(snapshot_b64, "base64")); + for (const update of updates_b64) Y.applyUpdate(doc, Buffer.from(update, "base64")); + const apply_result = cmp.applyOps(doc, ops, catalog); + return { apply_result, projection: cmp.project(doc, catalog) }; + } finally { + doc.destroy(); + } +}; let pass = 0, fail = 0; const check = (name, cond, extra = "") => { @@ -59,7 +98,9 @@ const check = (name, cond, extra = "") => { console.log("== no-mock CRDT POC through the real doc-host sidecar =="); console.log(`host=${HOST} cmp-pin=${CMP}`); -const health = await (await fetch(HOST + "/health")).json(); +const healthResponse = await fetch(HOST + "/health", { signal: AbortSignal.timeout(10_000) }); +if (!healthResponse.ok) throw new Error(`sidecar health returned ${healthResponse.status}`); +const health = await healthResponse.json(); console.log(`dochost /health -> ${JSON.stringify(health)}\n`); // 1. MINT the bootstrap snapshot every replica forks from. @@ -128,7 +169,10 @@ const r1 = await post("/apply", { turn_id: "t1", catalog, }); -check("human set_widget applied", eq(r1.apply_result.applied, [humanOp.op_id]), JSON.stringify(r1.apply_result)); +const d1 = directApply([], [humanOp]); +check("human ApplyResult matches local executable package", eq(stableOutcomes(r1.apply_result), stableOutcomes(d1.apply_result)), JSON.stringify(r1.apply_result)); +check("human projection matches local executable package", eq(r1.projection, d1.projection)); +check("human set_widget applied", r1.apply_result.outcomes?.[0]?.op_id === humanOp.op_id && r1.apply_result.outcomes[0].outcome === "applied", JSON.stringify(r1.apply_result)); const r2 = await post("/apply", { snapshot_b64, @@ -138,9 +182,19 @@ const r2 = await post("/apply", { turn_id: "t2", catalog, }); +const d2 = directApply([r1.update_b64], [agentAdd, agentConnect]); +check( + "agent ApplyResult matches local executable package", + eq(stableOutcomes(r2.apply_result), stableOutcomes(d2.apply_result)), + JSON.stringify(r2.apply_result), +); +check("agent projection matches local executable package", eq(r2.projection, d2.projection)); check( "agent add_node+connect applied", - eq(r2.apply_result.applied, [agentAdd.op_id, agentConnect.op_id]), + eq(r2.apply_result.outcomes?.map(({ op_id, outcome }) => ({ op_id, outcome })), [ + { op_id: agentAdd.op_id, outcome: "applied" }, + { op_id: agentConnect.op_id, outcome: "applied" }, + ]), JSON.stringify(r2.apply_result), ); @@ -149,6 +203,30 @@ const hostProj = r2.projection; const hostK = hostProj.nodes.find((n) => String(n.id) === String(KSAMPLER.id)); check("host: human seed edit present", hostK && Number(hostK.widgets_values[0]) === 424242, JSON.stringify(hostK?.widgets_values)); check("host: agent node present", !!hostProj.nodes.find((n) => String(n.id) === String(newNodeId))); +check("host: agent link present", eq(hostProj.links.find((link) => String(link[0]) === String(newLinkId)), + [newLinkId, newNodeId, 0, KSAMPLER.id, 1, "CONDITIONING"])); + +// A real refusal pins comparison of the stable reason code (never its +// intentionally human/volatile message). +const rejectedOp = { ...humanOp, op_id: opId(), stamp: [2, "human:jo"], widget: "not_a_real_widget" }; +const r3 = await post("/apply", { + snapshot_b64, + updates_b64: [r1.update_b64, r2.update_b64], + ops: [rejectedOp], + actor: "human:jo", + turn_id: "t3-rejection-probe", + catalog, +}); +const d3 = directApply([r1.update_b64, r2.update_b64], [rejectedOp]); +check( + "rejected ApplyResult and stable reason code match local executable package", + eq(stableOutcomes(r3.apply_result), stableOutcomes(d3.apply_result)), + JSON.stringify(r3.apply_result), +); +check("unknown widget is rejected", r3.apply_result.outcomes?.[0]?.outcome === "rejected" + && r3.apply_result.outcomes[0].reason?.code === "unknown_widget"); +check("rejected batch projection matches local executable package", eq(r3.projection, d3.projection)); +check("rejection leaves graph unchanged", eq(r3.projection, hostProj)); // 4. FOLLOWER converges from the host DELTAS only (raw-struct fan-out). // /project folds snapshot + the two host updates and projects — this is diff --git a/examples/dochost-poc/run.sh b/examples/dochost-poc/run.sh index 8556ec0..880b027 100755 --- a/examples/dochost-poc/run.sh +++ b/examples/dochost-poc/run.sh @@ -1,34 +1,77 @@ #!/usr/bin/env bash -# Build the applier (this repo) + the real doc-host sidecar (from a cloud checkout), -# start the sidecar on :8095, and run the no-mock POC driver. No mocks, no /tmp state. +# Pack the exact checked-out applier, install it into a disposable copy of the +# real doc-host sidecar, start that copy on :8095, and run the no-mock POC driver. # # Usage: # DOCHOST_SRC=/path/to/cloud-main/services/agent/dochost ./examples/dochost-poc/run.sh # # DOCHOST_SRC must point at services/agent/dochost from Comfy-Org/cloud main. -# Its `npm ci` pulls the published @comfyorg/comfy-multi-player@0.1.0 applier. set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" PORT="${PORT:-8095}" DOCHOST_SRC="${DOCHOST_SRC:-$REPO_ROOT/../cloud/services/agent/dochost}" +STAGE_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/cmp-dochost.XXXXXX")" +DOCHOST_STAGE="$STAGE_ROOT/dochost" +ARTIFACTS="$STAGE_ROOT/artifacts" +SIDECAR="" -echo "== 1/4 build applier ($REPO_ROOT) ==" -( cd "$REPO_ROOT" && npm ci && npm run build ) +cleanup() { + if [ -n "$SIDECAR" ]; then + kill "$SIDECAR" 2>/dev/null || true + wait "$SIDECAR" 2>/dev/null || true + fi + rm -rf "$STAGE_ROOT" +} +trap cleanup EXIT +trap 'exit 130' HUP INT TERM + +echo "== 1/4 build and pack applier ($REPO_ROOT) ==" +mkdir -p "$ARTIFACTS" "$DOCHOST_STAGE" +( cd "$REPO_ROOT" && npm run build && npm pack --json --pack-destination "$ARTIFACTS" > "$ARTIFACTS/pack.json" ) +TARBALL_NAME="$(node -e 'const fs=require("node:fs"); const rows=JSON.parse(fs.readFileSync(process.argv[1], "utf8")); if(rows.length !== 1 || !rows[0].filename) process.exit(1); process.stdout.write(rows[0].filename)' "$ARTIFACTS/pack.json")" +TARBALL="$ARTIFACTS/$TARBALL_NAME" +echo "artifact sha256: $(sha256sum "$TARBALL" | cut -d' ' -f1)" +mkdir -p "$ARTIFACTS/unpacked" +tar -xzf "$TARBALL" -C "$ARTIFACTS/unpacked" -echo "== 2/4 build doc-host sidecar ($DOCHOST_SRC) ==" -( cd "$DOCHOST_SRC" && npm ci && npm run build ) -# One Yjs instance only: a nested copy breaks Yjs instanceof checks and makes -# project() throw "could not be cloned". npm ci dedupes; belt-and-suspenders: -rm -rf "$DOCHOST_SRC/node_modules/@comfyorg/comfy-multi-player/node_modules/yjs" 2>/dev/null || true +echo "== 2/4 stage and build doc-host sidecar ($DOCHOST_SRC) ==" +tar -C "$DOCHOST_SRC" --exclude='./node_modules' --exclude='./dist' --exclude='./.git' -cf - . | tar -C "$DOCHOST_STAGE" -xf - +( cd "$DOCHOST_STAGE" && npm ci && npm install --no-save "$TARBALL" && npm run build ) +node "$REPO_ROOT/examples/dochost-poc/verify-package-identity.mjs" "$ARTIFACTS/unpacked/package" "$DOCHOST_STAGE" +( cd "$DOCHOST_STAGE" && node --input-type=module - <<'NODE' +import { createRequire } from "node:module"; +import { realpathSync } from "node:fs"; +import { join, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +const stage = realpathSync(process.cwd()); +const fromHost = createRequire(join(stage, "package.json")); +const cmpRoot = realpathSync(join(stage, "node_modules/@comfyorg/comfy-multi-player")); +const fromCmp = createRequire(join(cmpRoot, "package.json")); +// The real package exports an import condition only, just like the ESM server. +const cmpEntry = realpathSync(fileURLToPath(import.meta.resolve("@comfyorg/comfy-multi-player"))); +if (!cmpEntry.startsWith(`${cmpRoot}${sep}`)) throw new Error("staged module resolver escaped installed CMP"); +const hostYjs = realpathSync(fromHost.resolve("yjs")); +const cmpYjs = realpathSync(fromCmp.resolve("yjs")); +if (hostYjs !== cmpYjs) throw new Error(`doc-host and CMP resolve different Yjs copies: ${hostYjs} != ${cmpYjs}`); +NODE +) echo "== 3/4 start sidecar on :$PORT ==" -( cd "$DOCHOST_SRC" && PORT="$PORT" node dist/server.js ) & +if curl -sf --connect-timeout 0.1 --max-time 0.2 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then + echo "refusing to reuse an existing healthy service on :$PORT" >&2 + exit 1 +fi +( cd "$DOCHOST_STAGE" && exec env PORT="$PORT" node dist/server.js ) & SIDECAR=$! -trap 'kill "$SIDECAR" 2>/dev/null || true' EXIT ready=0 for _ in $(seq 1 30); do - if curl -sf --connect-timeout 0.1 --max-time 0.2 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then + if ! kill -0 "$SIDECAR" 2>/dev/null; then + wait "$SIDECAR" || true + echo "sidecar exited before becoming healthy on :$PORT" >&2 + exit 1 + fi + if curl -sf --connect-timeout 0.1 --max-time 0.2 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1 && kill -0 "$SIDECAR" 2>/dev/null; then ready=1 break fi diff --git a/examples/dochost-poc/verify-package-identity.mjs b/examples/dochost-poc/verify-package-identity.mjs new file mode 100644 index 0000000..ebeb4f0 --- /dev/null +++ b/examples/dochost-poc/verify-package-identity.mjs @@ -0,0 +1,54 @@ +import { createHash } from "node:crypto"; +import { readdirSync, readFileSync, realpathSync } from "node:fs"; +import { join, relative, resolve, sep } from "node:path"; + +const [packedRootArg, stageArg] = process.argv.slice(2); + +function fail(message) { + console.error(`package identity mismatch: ${message}`); + process.exit(1); +} + +if (!packedRootArg || !stageArg) fail("expected packed package root and stage path"); + +const packedRoot = realpathSync(packedRootArg); +const stage = realpathSync(stageArg); +const installedRoot = realpathSync(join(stage, "node_modules/@comfyorg/comfy-multi-player")); +const stagePrefix = `${stage}${sep}`; +if (!installedRoot.startsWith(stagePrefix)) fail("installed package resolves outside the disposable stage"); + +function files(root, directory = "dist") { + const absolute = join(root, directory); + return readdirSync(absolute, { withFileTypes: true }) + .flatMap((entry) => { + const name = join(directory, entry.name); + if (entry.isDirectory()) return files(root, name); + if (!entry.isFile()) fail(`${name} is not a regular file`); + return [name]; + }) + .sort(); +} + +const expectedFiles = files(packedRoot); +const installedFiles = files(installedRoot); +if (JSON.stringify(expectedFiles) !== JSON.stringify(installedFiles)) { + fail(`dist file set differs: packed=${expectedFiles.join(",")} installed=${installedFiles.join(",")}`); +} + +for (const name of expectedFiles) { + const expected = readFileSync(join(packedRoot, name)); + const actual = readFileSync(join(installedRoot, name)); + const digest = (bytes) => createHash("sha256").update(bytes).digest("hex"); + if (digest(expected) !== digest(actual)) fail(`${name} bytes differ`); +} + +const installedPackage = JSON.parse(readFileSync(join(installedRoot, "package.json"), "utf8")); +const packedPackage = JSON.parse(readFileSync(join(packedRoot, "package.json"), "utf8")); +if (installedPackage.name !== packedPackage.name || installedPackage.version !== packedPackage.version) { + fail("package name or version differs"); +} +if (!readFileSync(join(installedRoot, "package.json")).equals(readFileSync(join(packedRoot, "package.json")))) { + fail("package manifest bytes differ (including exports and dependencies)"); +} + +process.stdout.write(`${relative(resolve(stage), installedRoot)}: ${expectedFiles.length} dist files verified\n`); From f61157b2f73caf78537e061e317a187b83b83bc0 Mon Sep 17 00:00:00 2001 From: bymyself Date: Fri, 18 Sep 2026 02:15:10 -0700 Subject: [PATCH 3/6] test: satisfy Fallow for doc-host harness --- .../dochost-poc/verify-package-identity.mjs | 1 + test/dochost-driver.test.ts | 119 ++++++++++++------ 2 files changed, 80 insertions(+), 40 deletions(-) diff --git a/examples/dochost-poc/verify-package-identity.mjs b/examples/dochost-poc/verify-package-identity.mjs index ebeb4f0..7dbd3ea 100644 --- a/examples/dochost-poc/verify-package-identity.mjs +++ b/examples/dochost-poc/verify-package-identity.mjs @@ -1,3 +1,4 @@ +// fallow-ignore-file unused-file -- invoked by run.sh and spawn-based portable harness tests import { createHash } from "node:crypto"; import { readdirSync, readFileSync, realpathSync } from "node:fs"; import { join, relative, resolve, sep } from "node:path"; diff --git a/test/dochost-driver.test.ts b/test/dochost-driver.test.ts index d1b8587..00bb168 100644 --- a/test/dochost-driver.test.ts +++ b/test/dochost-driver.test.ts @@ -1,4 +1,4 @@ -import { createServer } from "node:http"; +import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; import { spawn } from "node:child_process"; import { mkdtempSync, rmSync, symlinkSync } from "node:fs"; import { tmpdir } from "node:os"; @@ -8,51 +8,90 @@ import * as Y from "yjs"; import { applyOps, mint, project, type Op, type WidgetCatalog, type WorkflowJSON } from "../src/index.js"; type Body = Record; +type FixtureState = { applyNumber: number }; const servers: ReturnType[] = []; +async function readBody(req: IncomingMessage): Promise { + const chunks: Buffer[] = []; + for await (const chunk of req) chunks.push(Buffer.from(chunk)); + return chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) as Body : {}; +} + +type Drift = (applyNumber: number, body: Body, result: Body) => Body; + +function driftOutcome(applyNumber: number, _body: Body, result: Body) { + if (applyNumber !== 1) return result; + const changed = structuredClone(result); + (changed.outcomes as { outcome: string }[])[0]!.outcome = "no-op"; + return changed; +} + +function driftOrder(applyNumber: number, _body: Body, result: Body) { + if (applyNumber !== 2) return result; + const changed = structuredClone(result); + (changed.outcomes as unknown[]).reverse(); + return changed; +} + +function driftReason(applyNumber: number, _body: Body, result: Body, code?: string) { + if (applyNumber !== 3) return result; + const changed = structuredClone(result); + const reason = ((changed.outcomes as Body[])[0]!.reason as Body); + if (code) reason.code = code; + reason.message = code ? "message changes are deliberately ignored" : "different volatile prose"; + return changed; +} + +const drifts: Record = { + count: (applyNumber, _body, result) => applyNumber === 1 + ? { ...result, ops_seen: (result.ops_seen as number) + 1 } + : result, + legacy: (applyNumber, body, result) => applyNumber === 1 + ? { applied: [(body.ops as Op[])[0]!.op_id] } + : result, + message: (applyNumber, body, result) => driftReason(applyNumber, body, result), + order: driftOrder, + outcome: driftOutcome, + reason: (applyNumber, body, result) => driftReason(applyNumber, body, result, "different_code"), +}; + +function applyFixtureDrift(mode: string, applyNumber: number, body: Body, result: Body): Body { + return drifts[mode]?.(applyNumber, body, result) ?? result; +} + +async function serveFixtureRequest( + mode: string, + state: FixtureState, + url: string | undefined, + body: Body, + res: ServerResponse, +) { + res.setHeader("content-type", "application/json"); + if (url === "/health") return res.end('{"ok":true,"fixture":"loopback-not-cloud"}'); + if (url === "/mint") { + const doc = mint(body.workflow as WorkflowJSON, body.catalog as WidgetCatalog); + return res.end(JSON.stringify({ snapshot_b64: Buffer.from(Y.encodeStateAsUpdate(doc)).toString("base64") })); + } + const doc = new Y.Doc(); + Y.applyUpdate(doc, Buffer.from(body.snapshot_b64 as string, "base64")); + for (const update of body.updates_b64 as string[]) Y.applyUpdate(doc, Buffer.from(update, "base64")); + if (url === "/project") return res.end(JSON.stringify({ projection: project(doc, body.catalog as WidgetCatalog) })); + const before = Y.encodeStateVector(doc); + state.applyNumber++; + const rawResult = applyOps(doc, body.ops as Op[], body.catalog as WidgetCatalog) as unknown as Body; + const apply_result = applyFixtureDrift(mode, state.applyNumber, body, rawResult); + const projected = project(doc, body.catalog as WidgetCatalog); + const projection = mode === "projection" && state.applyNumber === 1 ? { ...projected, extra: true } : projected; + res.end(JSON.stringify({ apply_result, projection, update_b64: Buffer.from(Y.encodeStateAsUpdate(doc, before)).toString("base64") })); +} + async function run(mode = "match", packageRoot = resolve(".")) { const requests: { path: string; body: Body }[] = []; - let applyNumber = 0; + const state: FixtureState = { applyNumber: 0 }; const server = createServer(async (req, res) => { - const chunks: Buffer[] = []; - for await (const chunk of req) chunks.push(Buffer.from(chunk)); - const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) as Body : {}; + const body = await readBody(req); requests.push({ path: req.url!, body }); - res.setHeader("content-type", "application/json"); - if (req.url === "/health") return res.end('{"ok":true,"fixture":"loopback-not-cloud"}'); - if (req.url === "/mint") { - const doc = mint(body.workflow as WorkflowJSON, body.catalog as WidgetCatalog); - return res.end(JSON.stringify({ snapshot_b64: Buffer.from(Y.encodeStateAsUpdate(doc)).toString("base64") })); - } - const doc = new Y.Doc(); - Y.applyUpdate(doc, Buffer.from(body.snapshot_b64 as string, "base64")); - for (const update of body.updates_b64 as string[]) Y.applyUpdate(doc, Buffer.from(update, "base64")); - if (req.url === "/project") return res.end(JSON.stringify({ projection: project(doc, body.catalog as WidgetCatalog) })); - const before = Y.encodeStateVector(doc); - let apply_result: Body = applyOps(doc, body.ops as Op[], body.catalog as WidgetCatalog) as unknown as Body; - const projectionResult = project(doc, body.catalog as WidgetCatalog); - applyNumber++; - if (mode === "legacy" && applyNumber === 1) apply_result = { applied: [(body.ops as Op[])[0]!.op_id] }; - if (mode === "outcome" && applyNumber === 1) { - apply_result = structuredClone(apply_result); - (apply_result.outcomes as { outcome: string }[])[0]!.outcome = "no-op"; - } - if (mode === "order" && applyNumber === 2) { - apply_result = structuredClone(apply_result); - (apply_result.outcomes as unknown[]).reverse(); - } - if (mode === "count" && applyNumber === 1) apply_result = { ...apply_result, ops_seen: (apply_result.ops_seen as number) + 1 }; - if (mode === "reason" && applyNumber === 3) { - apply_result = structuredClone(apply_result); - ((apply_result.outcomes as Body[])[0]!.reason as Body).code = "different_code"; - ((apply_result.outcomes as Body[])[0]!.reason as Body).message = "message changes are deliberately ignored"; - } - if (mode === "message" && applyNumber === 3) { - apply_result = structuredClone(apply_result); - ((apply_result.outcomes as Body[])[0]!.reason as Body).message = "different volatile prose"; - } - const projection = mode === "projection" && applyNumber === 1 ? { ...projectionResult, extra: true } : projectionResult; - res.end(JSON.stringify({ apply_result, projection, update_b64: Buffer.from(Y.encodeStateAsUpdate(doc, before)).toString("base64") })); + await serveFixtureRequest(mode, state, req.url, body, res); }); servers.push(server); await new Promise((done) => server.listen(0, "127.0.0.1", done)); From 3fadb7ee9fa7f1587d06ec13e1590da46abeea60 Mon Sep 17 00:00:00 2001 From: bymyself Date: Fri, 18 Sep 2026 10:23:41 -0700 Subject: [PATCH 4/6] test: expose rejected-batch delta mutations --- test/dochost-driver.test.ts | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/test/dochost-driver.test.ts b/test/dochost-driver.test.ts index 00bb168..90c1337 100644 --- a/test/dochost-driver.test.ts +++ b/test/dochost-driver.test.ts @@ -82,6 +82,17 @@ async function serveFixtureRequest( const apply_result = applyFixtureDrift(mode, state.applyNumber, body, rawResult); const projected = project(doc, body.catalog as WidgetCatalog); const projection = mode === "projection" && state.applyNumber === 1 ? { ...projected, extra: true } : projected; + if (mode === "hidden-rejection-mutation" && state.applyNumber === 3) { + doc.getMap("meta").set("fixture_hidden_rejection_mutation", true); + } + if (mode === "trailing-operation-applied" && state.applyNumber === 3) { + const trailing = (body.ops as Op[])[1]; + if (!trailing) throw new Error("trailing-operation fixture requires a second rejected-batch operation"); + const trailingResult = applyOps(doc, [trailing], body.catalog as WidgetCatalog); + if (trailingResult.outcomes[0]?.outcome !== "applied") { + throw new Error(`trailing-operation fixture could not apply operation: ${JSON.stringify(trailingResult)}`); + } + } res.end(JSON.stringify({ apply_result, projection, update_b64: Buffer.from(Y.encodeStateAsUpdate(doc, before)).toString("base64") })); } @@ -130,6 +141,15 @@ describe("dochost driver executable-package oracle (tiny loopback fixture, not c expect(result.code, result.output).toBe(0); }); + it.each([ + ["hidden-rejection-mutation", "FAIL rejected batch leaves encoded document state unchanged"], + ["trailing-operation-applied", "FAIL batch-aborted trailing operation is absent from __applied"], + ])("fails closed for %s", async (mode, expectedFailure) => { + const result = await run(mode); + expect(result.code, result.output).toBe(1); + expect(result.output).toContain(expectedFailure); + }); + it("imports the executable package from a path containing spaces and URL delimiters", async () => { const directory = mkdtempSync(join(tmpdir(), "cmp-driver-")); const checkout = join(directory, "checkout # with spaces"); From d18aa7397867f7b688a7f90e0420c477b5108de8 Mon Sep 17 00:00:00 2001 From: bymyself Date: Fri, 18 Sep 2026 10:24:50 -0700 Subject: [PATCH 5/6] fix: verify rejected doc-host batch delta --- examples/dochost-poc/README.md | 4 ++- examples/dochost-poc/dochost-driver.mjs | 33 +++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/examples/dochost-poc/README.md b/examples/dochost-poc/README.md index dcd7674..fafb9a0 100644 --- a/examples/dochost-poc/README.md +++ b/examples/dochost-poc/README.md @@ -43,7 +43,9 @@ Checked-out package ── pack ──► disposable sidecar ──► HTTP resu - 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, including a real unknown-widget refusal. +- 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. diff --git a/examples/dochost-poc/dochost-driver.mjs b/examples/dochost-poc/dochost-driver.mjs index 3011f9b..32d3e22 100644 --- a/examples/dochost-poc/dochost-driver.mjs +++ b/examples/dochost-poc/dochost-driver.mjs @@ -209,15 +209,16 @@ check("host: agent link present", eq(hostProj.links.find((link) => String(link[0 // A real refusal pins comparison of the stable reason code (never its // intentionally human/volatile message). const rejectedOp = { ...humanOp, op_id: opId(), stamp: [2, "human:jo"], widget: "not_a_real_widget" }; +const abortedOp = { ...humanOp, op_id: opId(), stamp: [3, "human:jo"], value: 515151 }; const r3 = await post("/apply", { snapshot_b64, updates_b64: [r1.update_b64, r2.update_b64], - ops: [rejectedOp], + ops: [rejectedOp, abortedOp], actor: "human:jo", turn_id: "t3-rejection-probe", catalog, }); -const d3 = directApply([r1.update_b64, r2.update_b64], [rejectedOp]); +const d3 = directApply([r1.update_b64, r2.update_b64], [rejectedOp, abortedOp]); check( "rejected ApplyResult and stable reason code match local executable package", eq(stableOutcomes(r3.apply_result), stableOutcomes(d3.apply_result)), @@ -225,9 +226,37 @@ check( ); check("unknown widget is rejected", r3.apply_result.outcomes?.[0]?.outcome === "rejected" && r3.apply_result.outcomes[0].reason?.code === "unknown_widget"); +check("valid trailing operation is batch_aborted", r3.apply_result.outcomes?.[1]?.op_id === abortedOp.op_id + && r3.apply_result.outcomes[1].outcome === "rejected" + && r3.apply_result.outcomes[1].reason?.code === "batch_aborted"); check("rejected batch projection matches local executable package", eq(r3.projection, d3.projection)); check("rejection leaves graph unchanged", eq(r3.projection, hostProj)); +// Reconstruct both documents from the same bootstrap and prior HOST deltas, +// then fold the returned rejection delta into only the after-document. This +// direct comparison never enters either the host or follower update stream. +const rejectionBefore = new Y.Doc(); +const rejectionAfter = new Y.Doc(); +try { + for (const doc of [rejectionBefore, rejectionAfter]) { + Y.applyUpdate(doc, Buffer.from(snapshot_b64, "base64")); + Y.applyUpdate(doc, Buffer.from(r1.update_b64, "base64")); + Y.applyUpdate(doc, Buffer.from(r2.update_b64, "base64")); + } + Y.applyUpdate(rejectionAfter, Buffer.from(r3.update_b64, "base64")); + check( + "rejected batch leaves encoded document state unchanged", + Buffer.from(Y.encodeStateAsUpdate(rejectionBefore)).equals(Buffer.from(Y.encodeStateAsUpdate(rejectionAfter))), + ); + check( + "batch-aborted trailing operation is absent from __applied", + !rejectionAfter.getMap("__applied").has(abortedOp.op_id), + ); +} finally { + rejectionBefore.destroy(); + rejectionAfter.destroy(); +} + // 4. FOLLOWER converges from the host DELTAS only (raw-struct fan-out). // /project folds snapshot + the two host updates and projects — this is // exactly what a follower Y.Doc integrates via applyUpdate. From b5179cc0d8490f7bfd886626a35665ae946b1913 Mon Sep 17 00:00:00 2001 From: bymyself Date: Fri, 18 Sep 2026 10:30:56 -0700 Subject: [PATCH 6/6] test: verify rejected operation stays out of applied ledger --- examples/dochost-poc/dochost-driver.mjs | 4 ++++ test/dochost-driver.test.ts | 5 +++++ 2 files changed, 9 insertions(+) diff --git a/examples/dochost-poc/dochost-driver.mjs b/examples/dochost-poc/dochost-driver.mjs index 32d3e22..4fb97ed 100644 --- a/examples/dochost-poc/dochost-driver.mjs +++ b/examples/dochost-poc/dochost-driver.mjs @@ -248,6 +248,10 @@ try { "rejected batch leaves encoded document state unchanged", Buffer.from(Y.encodeStateAsUpdate(rejectionBefore)).equals(Buffer.from(Y.encodeStateAsUpdate(rejectionAfter))), ); + check( + "rejected operation is absent from __applied", + !rejectionAfter.getMap("__applied").has(rejectedOp.op_id), + ); check( "batch-aborted trailing operation is absent from __applied", !rejectionAfter.getMap("__applied").has(abortedOp.op_id), diff --git a/test/dochost-driver.test.ts b/test/dochost-driver.test.ts index 90c1337..a55ce1b 100644 --- a/test/dochost-driver.test.ts +++ b/test/dochost-driver.test.ts @@ -85,6 +85,10 @@ async function serveFixtureRequest( if (mode === "hidden-rejection-mutation" && state.applyNumber === 3) { doc.getMap("meta").set("fixture_hidden_rejection_mutation", true); } + if (mode === "rejected-operation-recorded" && state.applyNumber === 3) { + const rejected = (body.ops as Op[])[0]!; + doc.getMap("__applied").set(rejected.op_id, true); + } if (mode === "trailing-operation-applied" && state.applyNumber === 3) { const trailing = (body.ops as Op[])[1]; if (!trailing) throw new Error("trailing-operation fixture requires a second rejected-batch operation"); @@ -143,6 +147,7 @@ describe("dochost driver executable-package oracle (tiny loopback fixture, not c it.each([ ["hidden-rejection-mutation", "FAIL rejected batch leaves encoded document state unchanged"], + ["rejected-operation-recorded", "FAIL rejected operation is absent from __applied"], ["trailing-operation-applied", "FAIL batch-aborted trailing operation is absent from __applied"], ])("fails closed for %s", async (mode, expectedFailure) => { const result = await run(mode);