test: downstream client compatibility gate (Phase 1) (#7923)

* docs: design for downstream client compatibility tests

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: Phase 1 implementation plan for downstream compat tests

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(downstream): add golden wire-vector generator

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(downstream): add committed golden wire-vectors fixture

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(downstream): assert wire-vectors fixture stability + consistency

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(downstream): pin socket.io handshake + USER_CHANGES sequence

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(downstream): snapshot client-facing HTTP API shapes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(downstream): add client manifest (entries disabled pending Phase 2)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(downstream): add downstream-smoke workflow (boot/self-check/teardown + manifest scaffold)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(downstream): validate settings rewrite + ignore docs/** (Qodo)

Fail fast if the template's port/auth literals drift so a no-op sed can't
silently boot the smoke server on the wrong port/auth. Also ignore docs/**
(not just doc/**) so docs-only PRs don't trigger the boot job.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.github/workflows/downstream-smoke.yml

@@ -0,0 +1,111 @@
+name: Downstream smoke
+
+# Boots a real Etherpad from the PR and verifies the separate downstream clients
+# (Rust terminal editor, Node CLI, desktop/mobile) still round-trip against it.
+# Phase 1 lands the boot/healthcheck/self-check/teardown harness + manifest; the
+# per-client matrix activates as each client flips `enabled:true` in clients.json.
+
+on:
+  pull_request:
+    paths-ignore:
+      - "doc/**"
+      - "docs/**"
+  schedule:
+    - cron: '0 4 * * *'   # nightly against the default branch
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    name: Boot + downstream clients
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    env:
+      PNPM_HOME: ~/.pnpm-store
+      APIKEY: downstream-smoke-key
+    steps:
+      - name: Checkout core (PR)
+        uses: actions/checkout@v6
+
+      - uses: actions/cache@v5
+        name: Cache pnpm store
+        with:
+          path: ${{ env.PNPM_HOME }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - uses: pnpm/action-setup@v6
+        name: Install pnpm
+        with:
+          run_install: false
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+
+      - name: Boot Etherpad on :9003 (apikey auth)
+        run: |
+          # The template ships a literal "port": 9001 and sso auth; rewrite both.
+          # (PORT env is ignored once the settings file specifies a port.)
+          sed -e 's#"port": 9001,#"port": 9003,#' \
+              -e 's#${AUTHENTICATION_METHOD:sso}#apikey#' \
+              settings.json.template > settings.json
+          # Fail fast if the template format drifted and sed silently no-op'd.
+          grep -q '"port": 9003,' settings.json \
+            || { echo "::error::port rewrite failed — settings.json.template format changed"; exit 1; }
+          grep -q '"authenticationMethod": "apikey"' settings.json \
+            || { echo "::error::auth rewrite failed — settings.json.template format changed"; exit 1; }
+          printf '%s' "$APIKEY" > APIKEY.txt
+          pnpm run prod > /tmp/ep.log 2>&1 &
+          echo $! > /tmp/ep.pid
+          echo "booted pid $(cat /tmp/ep.pid)"
+
+      - name: Wait for healthcheck
+        run: |
+          for i in $(seq 1 60); do
+            if curl -fsS "http://localhost:9003/api/" >/dev/null 2>&1; then
+              echo "server up after ${i} tries"; exit 0
+            fi
+            sleep 2
+          done
+          echo "::error::server did not come up"; tail -50 /tmp/ep.log; exit 1
+
+      - name: Self-check — authenticated create + read roundtrip
+        run: |
+          K="$APIKEY"
+          curl -fsS "http://localhost:9003/api/1/createPad?apikey=${K}&padID=smoke&text=hi%0A" | tee /tmp/create.json
+          grep -q '"code":0' /tmp/create.json
+          curl -fsS "http://localhost:9003/api/1/getText?apikey=${K}&padID=smoke" | tee /tmp/get.json
+          grep -q '"text":"hi' /tmp/get.json
+
+      - name: Generate canonical wire-vectors
+        run: cd src && pnpm run vectors:gen
+
+      - name: Run enabled downstream clients
+        run: |
+          ENABLED=$(node -e 'const c=require("./src/tests/downstream/clients.json").filter(x=>x.enabled); process.stdout.write(JSON.stringify(c))')
+          if [ "$ENABLED" = "[]" ]; then
+            echo "No downstream clients enabled yet (Phase 1 harness only). Skipping."
+            exit 0
+          fi
+          # Phase 2 implements per-`kind` clone @ pinned ref + toolchain setup +
+          # vector injection (cp src/tests/fixtures/wire-vectors.json into the
+          # client) + `vectorTest` + `smokeCmd` against http://localhost:9003,
+          # iterating the entries in $ENABLED. Until a client is enabled this is
+          # a no-op so the harness lands green on its own.
+          echo "$ENABLED"
+
+      - name: Teardown (by PID, never pkill)
+        if: always()
+        run: |
+          if [ -f /tmp/ep.pid ]; then
+            kill "$(cat /tmp/ep.pid)" 2>/dev/null || true
+            echo "killed $(cat /tmp/ep.pid)"
+          fi

docs/superpowers/plans/2026-06-09-downstream-client-compat-tests-phase1.md

@@ -0,0 +1,633 @@
+# Downstream Client Compatibility Tests — Phase 1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a core-side compatibility gate (golden-vector + socket-sequence + HTTP-API-shape contract tests, plus a downstream-smoke workflow scaffold) so a PR against `develop` detects changes that would break the separate downstream clients.
+
+**Architecture:** Layer A — hermetic contract tests run inside core's existing mocha backend suite, anchored to a committed `wire-vectors.json` fixture generated from core's own `Changeset`/`AttributePool`. Layer B — a `downstream-smoke.yml` workflow that boots a real Etherpad on :9003, proves the boot→healthcheck→teardown cycle with a self-check, and is ready to matrix over a `clients.json` manifest as clients register in Phase 2.
+
+**Tech Stack:** TypeScript, mocha (`--import=tsx`), `assert/strict`, supertest + socket.io-client via `common.ts` helpers, GitHub Actions.
+
+**Spec:** `docs/superpowers/specs/2026-06-09-downstream-client-compat-tests-design.md`
+
+**Scope note:** This plan is **Phase 1 only** (all changes in `ether/etherpad`). Phase 2 (wiring each client repo's `test:vectors` + smoke and registering it in the manifest) is one separate plan/PR per client repo and is out of scope here.
+
+---
+
+## File Structure
+
+- Create `src/tests/backend/specs/downstream/generate-vectors.ts` — pure module exporting `generateVectors(): WireVector[]`; the single source of truth for the canonical wire fixtures. Also runnable as a CLI to (re)write the fixture.
+- Create `src/tests/fixtures/wire-vectors.json` — committed canonical fixture (generated, never hand-edited).
+- Create `src/tests/backend/specs/downstream/wire-vectors.ts` — mocha spec asserting the committed fixture is stable and self-consistent.
+- Create `src/tests/backend/specs/downstream/wire-socket-sequence.ts` — mocha spec asserting the socket.io handshake + USER_CHANGES→ACCEPT_COMMIT sequence/shapes.
+- Create `src/tests/backend/specs/downstream/wire-http-api.ts` — mocha spec snapshotting client-facing HTTP API response shapes.
+- Create `src/tests/downstream/clients.json` — manifest of downstream clients (data; entries `enabled:false` until their Phase-2 smoke lands).
+- Create `.github/workflows/downstream-smoke.yml` — boot/healthcheck/self-check/teardown + manifest matrix scaffold.
+- Modify `src/package.json` — add `vectors:gen` script.
+
+All backend specs live under `specs/downstream/` so the existing `mocha ... --recursive tests/backend/specs` glob picks them up with zero config change.
+
+---
+
+## Task 1: Golden-vector generator module
+
+**Files:**
+- Create: `src/tests/backend/specs/downstream/generate-vectors.ts`
+- Test: `src/tests/backend/specs/downstream/wire-vectors.ts` (created in Task 3; this task is tested via Task 2's run)
+
+- [ ] **Step 1: Write the generator module**
+
+Create `src/tests/backend/specs/downstream/generate-vectors.ts`:
+
+```typescript
+'use strict';
+
+/**
+ * Single source of truth for the downstream wire-compatibility fixtures.
+ *
+ * Each vector is a self-contained changeset application: given `initialAText`
+ * and `pool`, applying `changeset` yields `resultAText`. Downstream clients
+ * (which reimplement Etherpad's changeset/attribpool decoders) consume the
+ * exact same JSON and must reproduce `resultAText`. See the Phase 1 plan.
+ *
+ * Runnable as a CLI to (re)write src/tests/fixtures/wire-vectors.json:
+ *   pnpm run vectors:gen
+ */
+
+import Changeset from '../../../../static/js/Changeset';
+import AttributePool from '../../../../static/js/AttributePool';
+
+export type WireVector = {
+  name: string;
+  initialText: string;
+  changeset: string;
+  pool: ReturnType<AttributePool['toJsonable']>;
+  resultText: string;
+};
+
+const vector = (
+  name: string,
+  initialText: string,
+  build: (pool: AttributePool) => string,
+): WireVector => {
+  const pool = new AttributePool();
+  const changeset = build(pool);
+  Changeset.checkRep(changeset);
+  return {
+    name,
+    initialText,
+    changeset,
+    pool: pool.toJsonable(),
+    resultText: Changeset.applyToText(changeset, initialText),
+  };
+};
+
+export const generateVectors = (): WireVector[] => [
+  vector('plain-insert', 'abc\n', () =>
+    Changeset.makeSplice('abc\n', 3, 0, 'XYZ')),
+
+  vector('plain-delete', 'abcdef\n', () =>
+    Changeset.makeSplice('abcdef\n', 1, 3, '')),
+
+  vector('formatted-insert', 'abc\n', (pool) =>
+    Changeset.makeSplice('abc\n', 3, 0, 'bold', [['bold', 'true']], pool)),
+
+  vector('multiline-insert', 'abc\n', () =>
+    Changeset.makeSplice('abc\n', 3, 0, 'one\ntwo\n')),
+
+  vector('attrib-reuse', 'abc\n', (pool) => {
+    // Two formatted inserts sharing one pool entry exercises pool index reuse.
+    const cs1 = Changeset.makeSplice('abc\n', 0, 0, 'A', [['bold', 'true']], pool);
+    const mid = Changeset.applyToText(cs1, 'abc\n');
+    const cs2 = Changeset.makeSplice(mid, mid.length - 1, 0, 'B', [['bold', 'true']], pool);
+    return Changeset.compose(cs1, cs2, pool);
+  }),
+];
+
+// CLI entry: write the canonical fixture to disk.
+if (require.main === module) {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const fs = require('fs');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const path = require('path');
+  const out = path.join(__dirname, '../../../fixtures/wire-vectors.json');
+  fs.writeFileSync(out, `${JSON.stringify(generateVectors(), null, 2)}\n`);
+  // eslint-disable-next-line no-console
+  console.log(`wrote ${out}`);
+}
+```
+
+- [ ] **Step 2: Add the `vectors:gen` script**
+
+In `src/package.json`, add to `"scripts"` (alongside the existing `test` entry):
+
+```json
+"vectors:gen": "tsx tests/backend/specs/downstream/generate-vectors.ts",
+```
+
+- [ ] **Step 3: Sanity-run the generator (no fixture committed yet)**
+
+Run from `src/`:
+```bash
+cd src && pnpm run vectors:gen
+```
+Expected: prints `wrote .../src/tests/fixtures/wire-vectors.json` and the file exists with 5 vectors. Verify each has non-empty `changeset` and a `resultText` that differs from `initialText`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/tests/backend/specs/downstream/generate-vectors.ts src/package.json
+git commit -m "test(downstream): add golden wire-vector generator"
+```
+
+---
+
+## Task 2: Commit the generated fixture
+
+**Files:**
+- Create: `src/tests/fixtures/wire-vectors.json`
+
+- [ ] **Step 1: Generate the fixture**
+
+Run from `src/`:
+```bash
+cd src && pnpm run vectors:gen
+```
+Expected: `src/tests/fixtures/wire-vectors.json` written.
+
+- [ ] **Step 2: Eyeball the fixture**
+
+Open `src/tests/fixtures/wire-vectors.json`. Confirm it is a JSON array of 5 objects, each with keys `name, initialText, changeset, pool, resultText`. The `pool` for `plain-insert`/`plain-delete`/`multiline-insert` has empty `numToAttrib`; `formatted-insert` and `attrib-reuse` contain a `bold,true` entry.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tests/fixtures/wire-vectors.json
+git commit -m "test(downstream): add committed golden wire-vectors fixture"
+```
+
+---
+
+## Task 3: Fixture stability + self-consistency spec
+
+**Files:**
+- Create: `src/tests/backend/specs/downstream/wire-vectors.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/tests/backend/specs/downstream/wire-vectors.ts`:
+
+```typescript
+'use strict';
+
+/**
+ * Guards the downstream wire-format contract:
+ *  - the committed fixture exactly matches a fresh regeneration (any drift is a
+ *    deliberate wire change and must be re-generated + reviewed in the same PR), and
+ *  - every vector is internally consistent under core's own Changeset engine.
+ */
+
+const assert = require('assert').strict;
+import fs from 'fs';
+import path from 'path';
+import Changeset from '../../../../static/js/Changeset';
+import {generateVectors} from './generate-vectors';
+
+const fixturePath = path.join(__dirname, '../../../fixtures/wire-vectors.json');
+
+describe(__filename, function () {
+  it('committed fixture matches a fresh regeneration', function () {
+    const committed = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+    const fresh = generateVectors();
+    assert.deepEqual(committed, fresh,
+      'wire-vectors.json is stale — run `pnpm run vectors:gen` and commit the result');
+  });
+
+  it('every vector applies to its result under core Changeset', function () {
+    for (const v of generateVectors()) {
+      Changeset.checkRep(v.changeset);
+      assert.equal(Changeset.applyToText(v.changeset, v.initialText), v.resultText,
+        `vector ${v.name} result mismatch`);
+    }
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it passes (fixture already committed)**
+
+Run from `src/`:
+```bash
+cd src && pnpm exec mocha --import=tsx --timeout 120000 --extension ts tests/backend/specs/downstream/wire-vectors.ts
+```
+Expected: 2 passing.
+
+- [ ] **Step 3: Prove the guard bites (temporary edit)**
+
+Hand-edit one `resultText` in `src/tests/fixtures/wire-vectors.json`, re-run the command above.
+Expected: the "committed fixture matches a fresh regeneration" test FAILS. Then `git checkout src/tests/fixtures/wire-vectors.json` to restore.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/tests/backend/specs/downstream/wire-vectors.ts
+git commit -m "test(downstream): assert wire-vectors fixture stability + consistency"
+```
+
+---
+
+## Task 4: Socket message-sequence spec
+
+**Files:**
+- Create: `src/tests/backend/specs/downstream/wire-socket-sequence.ts`
+
+Reference for helpers: `src/tests/backend/specs/messages.ts` (`common.connect`, `common.handshake`) and `src/tests/backend/common.ts`.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/tests/backend/specs/downstream/wire-socket-sequence.ts`:
+
+```typescript
+'use strict';
+
+/**
+ * Pins the socket.io message sequence + shapes that every realtime client
+ * depends on: handshake -> CLIENT_VARS, then USER_CHANGES -> ACCEPT_COMMIT.
+ * A change here is a wire-protocol change that will break downstream clients.
+ */
+
+const assert = require('assert').strict;
+const common = require('../../common');
+const padManager = require('../../../node/db/PadManager');
+import AttributePool from '../../../../static/js/AttributePool';
+import Changeset from '../../../../static/js/Changeset';
+
+describe(__filename, function () {
+  let agent: any;
+  let socket: any;
+  let padId: string;
+
+  before(async function () { agent = await common.init(); });
+
+  beforeEach(async function () {
+    padId = common.randomString();
+    const pad = await padManager.getPad(padId, 'init\n');
+    await pad.setText('init\n');
+    const res = await agent.get(`/p/${padId}`).expect(200);
+    socket = await common.connect(res);
+  });
+
+  afterEach(async function () {
+    if (socket != null) socket.close();
+    socket = null;
+  });
+
+  it('handshake returns CLIENT_VARS with the client-facing shape', async function () {
+    const {type, data} = await common.handshake(socket, padId);
+    assert.equal(type, 'CLIENT_VARS');
+    assert.ok(data.userId, 'CLIENT_VARS.userId missing');
+    assert.ok(data.collab_client_vars, 'collab_client_vars missing');
+    assert.equal(typeof data.collab_client_vars.rev, 'number');
+    assert.ok(data.collab_client_vars.initialAttributedText, 'initialAttributedText missing');
+  });
+
+  it('USER_CHANGES is acknowledged with ACCEPT_COMMIT and a bumped rev', async function () {
+    const {data: clientVars} = await common.handshake(socket, padId);
+    const rev = clientVars.collab_client_vars.rev;
+    const pool = new AttributePool();
+    const cs = Changeset.makeSplice('init\n', 4, 0, '-typed', [], pool);
+
+    const accepted = common.waitForSocketEvent(socket, 'message');
+    socket.emit('message', {
+      type: 'COLLABROOM',
+      component: 'pad',
+      data: {type: 'USER_CHANGES', baseRev: rev, changeset: cs, apool: pool.toJsonable()},
+    });
+    const msg: any = await accepted;
+    assert.equal(msg.type, 'COLLABROOM');
+    assert.equal(msg.data.type, 'ACCEPT_COMMIT');
+    assert.equal(msg.data.newRev, rev + 1);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it passes**
+
+Run from `src/`:
+```bash
+cd src && pnpm exec mocha --import=tsx --timeout 120000 --extension ts tests/backend/specs/downstream/wire-socket-sequence.ts
+```
+Expected: 2 passing. If `waitForSocketEvent`'s default 1s timeout is too tight on the ACCEPT_COMMIT, pass a larger `timeoutMs` (its 3rd arg) — e.g. `common.waitForSocketEvent(socket, 'message', 5000)`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tests/backend/specs/downstream/wire-socket-sequence.ts
+git commit -m "test(downstream): pin socket.io handshake + USER_CHANGES sequence"
+```
+
+---
+
+## Task 5: HTTP API shape spec
+
+**Files:**
+- Create: `src/tests/backend/specs/downstream/wire-http-api.ts`
+
+Reference: `src/tests/backend/specs/api/api.ts` for the `common.init()` agent + API-version pattern.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/tests/backend/specs/downstream/wire-http-api.ts`:
+
+```typescript
+'use strict';
+
+/**
+ * Snapshots the *shapes* (keys/types, not volatile values) of the HTTP API
+ * endpoints downstream clients call to create pads and round-trip text.
+ */
+
+const assert = require('assert').strict;
+const common = require('../../common');
+
+describe(__filename, function () {
+  let agent: any;
+  let apiVersion = 1;
+  const apiKey = common.apiKey;
+  const padId = common.randomString();
+  const ep = (point: string, qs: string) =>
+    `/api/${apiVersion}/${point}?apikey=${apiKey}&${qs}`;
+
+  before(async function () {
+    agent = await common.init();
+    const res = await agent.get('/api/').expect(200);
+    apiVersion = res.body.currentVersion;
+  });
+
+  it('createPad returns the standard {code,message,data} envelope', async function () {
+    const res = await agent.get(ep('createPad', `padID=${padId}&text=hello%0A`)).expect(200);
+    assert.deepEqual(Object.keys(res.body).sort(), ['code', 'data', 'message']);
+    assert.equal(res.body.code, 0);
+  });
+
+  it('setText + getText round-trips text through the documented shape', async function () {
+    await agent.get(ep('setText', `padID=${padId}&text=world%0A`)).expect(200);
+    const res = await agent.get(ep('getText', `padID=${padId}`)).expect(200);
+    assert.equal(res.body.code, 0);
+    assert.equal(typeof res.body.data.text, 'string');
+    assert.equal(res.body.data.text, 'world\n');
+  });
+
+  it('getRevisionsCount exposes a numeric revisions field', async function () {
+    const res = await agent.get(ep('getRevisionsCount', `padID=${padId}`)).expect(200);
+    assert.equal(res.body.code, 0);
+    assert.equal(typeof res.body.data.revisions, 'number');
+  });
+});
+```
+
+- [ ] **Step 2: Confirm the apiKey helper name**
+
+Run from `src/`:
+```bash
+cd src && grep -n "apiKey\|apikey" tests/backend/common.ts | head
+```
+Expected: a `common.apiKey` export (or similar). If the export is named differently, adjust the `apiKey` reference in the spec to match before running.
+
+- [ ] **Step 3: Run test to verify it passes**
+
+Run from `src/`:
+```bash
+cd src && pnpm exec mocha --import=tsx --timeout 120000 --extension ts tests/backend/specs/downstream/wire-http-api.ts
+```
+Expected: 3 passing.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/tests/backend/specs/downstream/wire-http-api.ts
+git commit -m "test(downstream): snapshot client-facing HTTP API shapes"
+```
+
+---
+
+## Task 6: Client manifest
+
+**Files:**
+- Create: `src/tests/downstream/clients.json`
+
+- [ ] **Step 1: Write the manifest**
+
+Create `src/tests/downstream/clients.json` (SHAs are current `main` HEADs at authoring; `enabled:false` until each client's Phase-2 smoke lands):
+
+```json
+[
+  {
+    "name": "etherpad-pad",
+    "repo": "https://github.com/ether/pad.git",
+    "ref": "31176d64ce746d45349e58ee6c0bb043052c6e66",
+    "kind": "rust",
+    "enabled": false,
+    "vectorTest": "cargo test --test vectors",
+    "smokeCmd": "cargo test --test smoke -- --ignored"
+  },
+  {
+    "name": "etherpad-cli-client",
+    "repo": "https://github.com/ether/etherpad-cli-client.git",
+    "ref": "edbe0bb70971e54514ebea672e4ad9b51fc55bff",
+    "kind": "node",
+    "enabled": false,
+    "vectorTest": "pnpm run test:vectors",
+    "smokeCmd": "pnpm run test:smoke"
+  },
+  {
+    "name": "etherpad-desktop",
+    "repo": "https://github.com/ether/etherpad-desktop.git",
+    "ref": "ad273c119f1926a8390c9908fc91f62fa2cf740f",
+    "kind": "desktop",
+    "enabled": false,
+    "vectorTest": "pnpm run test:vectors",
+    "smokeCmd": "pnpm run test:smoke"
+  }
+]
+```
+
+- [ ] **Step 2: Validate it is well-formed JSON**
+
+Run:
+```bash
+node -e "const c=require('./src/tests/downstream/clients.json'); console.log(c.length, c.map(x=>x.name).join(','))"
+```
+Expected: `3 etherpad-pad,etherpad-cli-client,etherpad-desktop`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/tests/downstream/clients.json
+git commit -m "test(downstream): add client manifest (entries disabled pending Phase 2)"
+```
+
+---
+
+## Task 7: Downstream-smoke workflow
+
+**Files:**
+- Create: `.github/workflows/downstream-smoke.yml`
+
+Reference an existing workflow (`.github/workflows/backend-tests.yml`) for the checkout/pnpm/node setup block this repo uses, and copy that setup verbatim into the job below.
+
+- [ ] **Step 1: Write the workflow**
+
+Create `.github/workflows/downstream-smoke.yml`:
+
+```yaml
+name: Downstream smoke
+
+on:
+  pull_request:
+  schedule:
+    - cron: '0 4 * * *'   # nightly against develop
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout core (PR)
+        uses: actions/checkout@v4
+
+      # --- Reuse core's standard node+pnpm setup (copy from backend-tests.yml) ---
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Boot Etherpad on :9003
+        env:
+          APIKEY: downstream-smoke-key
+        run: |
+          mkdir -p var
+          echo -n "$APIKEY" > APIKEY.txt
+          PORT=9003 pnpm run prod &
+          echo $! > /tmp/ep.pid
+
+      - name: Wait for healthcheck
+        run: |
+          for i in $(seq 1 60); do
+            if curl -fsS http://localhost:9003/api/ >/dev/null; then
+              echo "up"; exit 0
+            fi
+            sleep 2
+          done
+          echo "server did not come up"; exit 1
+
+      - name: Self-check (boot + API roundtrip proves the harness)
+        run: |
+          K=downstream-smoke-key
+          curl -fsS "http://localhost:9003/api/1/createPad?apikey=$K&padID=smoke&text=hi%0A"
+          curl -fsS "http://localhost:9003/api/1/getText?apikey=$K&padID=smoke" | grep -q '"text":"hi'
+
+      - name: Generate canonical wire-vectors
+        run: cd src && pnpm run vectors:gen
+
+      - name: Run enabled downstream clients
+        run: |
+          node -e '
+            const fs=require("fs");
+            const clients=require("./src/tests/downstream/clients.json").filter(c=>c.enabled);
+            if(!clients.length){console.log("No clients enabled yet (Phase 1).");process.exit(0);}
+            fs.writeFileSync("/tmp/clients.json",JSON.stringify(clients));
+          '
+          # Phase 2 wires per-kind clone + toolchain + vector injection + smoke here,
+          # iterating /tmp/clients.json. Until a client is enabled this is a no-op.
+
+      - name: Teardown (by PID, never pkill)
+        if: always()
+        run: |
+          if [ -f /tmp/ep.pid ]; then kill "$(cat /tmp/ep.pid)" 2>/dev/null || true; fi
+```
+
+- [ ] **Step 2: Confirm the boot command + port env**
+
+Run:
+```bash
+cd /home/jose/etherpad/etherpad-core-fresh && grep -nE '"prod"|"dev"|"start"' src/package.json
+grep -rn "process.env.PORT\|settings.port" src/node/utils/Settings.ts | head
+```
+Expected: confirm the script that starts a production server and that `PORT`/`APIKEY` are honored (Settings reads `process.env.PORT`). If the runnable script is named differently (e.g. `prod` vs `dev`), update the "Boot Etherpad" step to match. If APIKEY is read from a file rather than env, the `echo ... > APIKEY.txt` line already covers it.
+
+- [ ] **Step 3: Lint the workflow YAML**
+
+Run:
+```bash
+node -e "require('js-yaml')" 2>/dev/null && npx --yes js-yaml .github/workflows/downstream-smoke.yml >/dev/null && echo "valid yaml" || python3 -c "import yaml,sys; yaml.safe_load(open('.github/workflows/downstream-smoke.yml')); print('valid yaml')"
+```
+Expected: `valid yaml`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add .github/workflows/downstream-smoke.yml
+git commit -m "ci(downstream): add downstream-smoke workflow (boot/self-check/teardown + manifest scaffold)"
+```
+
+---
+
+## Task 8: Full backend-suite run + push
+
+**Files:** none (verification + integration)
+
+- [ ] **Step 1: Run the whole downstream spec group**
+
+Per the "always run backend tests" rule, run the new specs through the real mocha invocation the suite uses, from `src/`:
+```bash
+cd src && cross-env NODE_ENV=production pnpm exec mocha --import=tsx --timeout 120000 --extension ts --recursive tests/backend/specs/downstream
+```
+Expected: all specs in `tests/backend/specs/downstream/` pass (7 tests total across 3 files).
+
+- [ ] **Step 2: Confirm no regression in the fixture guard**
+
+Run from `src/`:
+```bash
+cd src && pnpm run vectors:gen && git diff --exit-code src/tests/fixtures/wire-vectors.json
+```
+Expected: exit 0 (regeneration is byte-identical to the committed fixture).
+
+- [ ] **Step 3: Push the branch and open the PR**
+
+```bash
+git push -u origin feat/downstream-client-compat-tests
+gh pr create --base develop \
+  --title "test: downstream client compatibility gate (Phase 1)" \
+  --body "Adds core-side contract tests (golden wire-vectors, socket-sequence, HTTP API shapes) and a downstream-smoke workflow scaffold so PRs detect changes that would break the separate CLI / terminal / desktop clients. Phase 2 wires each client repo's vector+smoke tests and flips its manifest entry to enabled. Spec + plan under docs/superpowers/. Closes nothing; tracks the downstream-compat initiative."
+```
+
+- [ ] **Step 4: Watch CI**
+
+Per the "check CI after PRs" rule, wait ~20s then:
+```bash
+gh pr checks --watch
+```
+Expected: backend tests green (now including the downstream specs); `Downstream smoke` green (self-check passes, no clients enabled yet). Fix any red before moving on.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Layer A golden vectors → Tasks 1–3. ✅
+- Layer A socket sequence → Task 4. ✅
+- Layer A HTTP API shapes → Task 5. ✅
+- Layer B manifest (pinned SHAs, `enabled` gate) → Task 6. ✅
+- Layer B workflow (boot :9003, healthcheck, vector generation, PID teardown, nightly+PR triggers) → Task 7. ✅
+- Flakiness mitigations: healthcheck-poll (Task 7 step), PID teardown (Task 7), :9003 (Task 7), no external clients on the gate yet so no flake surface (Task 6 `enabled:false`). ✅
+- Phasing: Phase 1 self-contained and green; Phase 2 explicitly out of scope. ✅
+
+**Verification-required tasks** (Task 5 step 2, Task 7 step 2) ask the engineer to confirm the exact `common.apiKey` export name and the production boot script/port handling against the live repo before running — these are real lookups, not placeholders, because those names are repo-version-specific.
+
+**Type consistency:** `WireVector` fields (`name/initialText/changeset/pool/resultText`) are defined in Task 1 and used identically in Tasks 2–3. `generateVectors()` signature is stable across Tasks 1/3. Manifest keys (`enabled`, `vectorTest`, `smokeCmd`) in Task 6 match the workflow's `.filter(c=>c.enabled)` consumer in Task 7.

docs/superpowers/specs/2026-06-09-downstream-client-compat-tests-design.md

@@ -0,0 +1,154 @@
+# Downstream Client Compatibility Tests — Design
+
+**Date:** 2026-06-09
+**Status:** Approved (brainstorming complete)
+**Target repo:** `ether/etherpad` (core), branch `develop`
+**Downstream repos in scope:** `etherpad-pad` (Rust terminal editor + `etherpad-client` crate), `etherpad-cli-client` (Node/TS CLI), `etherpad-desktop` (Electron desktop + Capacitor mobile)
+
+## Problem
+
+The three downstream clients live in **separate repos** and consume core's wire
+protocols rather than importing core as a library:
+
+- **etherpad-cli-client** ships its *own copies* of `Changeset.ts` + `AttributePool.ts`
+  and talks the socket.io `message` protocol. No test script today.
+- **etherpad-pad** (Rust) hand-rolls engine.io v4 / socket.io v4 + changeset
+  decoding in its `etherpad-client` crate. Has CI + a `mock-socket` test feature.
+- **etherpad-desktop** wraps / points at a core server URL. Has vitest + Playwright e2e + CI.
+
+A core PR can change the **HTTP API**, the **socket.io handshake / `message`
+sequence**, or the **changeset / attribpool wire format** and break these clients
+**silently**, because their CI never runs against the new core. The goal: a PR
+against core `develop` (and friends) must detect downstream breakage before merge.
+
+## Decisions (locked during brainstorming)
+
+| Decision | Choice |
+|---|---|
+| Detection strategy | **Hybrid**: fast contract tests in core (every PR) + downstream smoke (every PR) |
+| Smoke cadence | **Every PR** (with strong flakiness mitigations) |
+| How CI gets clients | **Git clone at pinned refs**, recorded in a manifest in core |
+| Contract depth | **Shared golden vectors** — core generates canonical fixtures, each client decodes the same fixtures with its own decoder |
+| Sequencing | **Phase by layer** — Phase 1 all core-side; Phase 2 one client repo at a time |
+
+## Architecture
+
+Two-layer compatibility gate on every core PR:
+
+```
+core PR ──┬─► Layer A: Contract tests (hermetic, fast, no network/clients)
+          │     • golden-vector assertions (changeset/attribpool roundtrip)
+          │     • socket.io message-sequence test (CLIENT_READY → CLIENT_VARS,
+          │       USER_CHANGES → ACCEPT_COMMIT / NEW_CHANGES)
+          │     • HTTP API shape snapshots
+          │
+          └─► Layer B: Downstream smoke (boots a real server, runs real clients)
+                • build + boot Etherpad from the PR on :9003 with a known API key
+                • healthcheck-poll until ready
+                • matrix over manifest: clone client @ pinned ref, set up toolchain,
+                  inject core's freshly-generated vectors, run client `test:vectors`,
+                  run client smoke: connect → create/open pad → write text →
+                  read back via HTTP API → assert equality
+                • tear down server by PID
+```
+
+## Layer A — Contract tests (Phase 1, core)
+
+### Golden vectors
+- Generator script: `src/tests/downstream/generate-vectors.ts` (run via a package
+  script, e.g. `pnpm run vectors:gen`).
+- Output fixture: `src/tests/fixtures/wire-vectors.json`. Each record:
+  `{ name, initialAText, changeset, pool, resultAText }` covering the operation
+  classes clients must decode: plain insert, delete, format/attrib op,
+  multi-line insert (char_bank ending in `\n`), attribpool reuse across ops.
+- Core test `src/tests/backend/specs/wire-vectors.ts`: regenerate in-memory and
+  assert it matches the committed fixture exactly (drift requires a deliberate
+  commit, which is the signal a wire change happened).
+
+### Socket message-sequence test
+- `src/tests/backend/specs/wire-socket-sequence.ts`: drive a socket.io client
+  against the in-process server, assert the handshake message sequence and the
+  shape of `CLIENT_VARS`, `USER_CHANGES` → `ACCEPT_COMMIT`, and broadcast
+  `NEW_CHANGES`. Reuses the existing backend socket test helpers.
+
+### HTTP API shape snapshots
+- `src/tests/backend/specs/wire-http-api.ts`: snapshot the response *shapes*
+  (keys / types, not volatile values) of the API endpoints clients call
+  (`createPad`, `setText`, `getText`, `getRevisionsCount`, session/auth as needed).
+
+These join the existing `backend-tests.yml` run — no new per-PR job, no new infra.
+
+## Layer B — Downstream smoke (Phase 1 scaffold, Phase 2 per client)
+
+### Manifest
+`src/tests/downstream/clients.json`:
+```json
+[
+  { "name": "etherpad-pad",        "repo": "https://github.com/ether/pad.git",                 "ref": "<sha on main>", "kind": "rust",    "smokeCmd": "..." },
+  { "name": "etherpad-cli-client", "repo": "https://github.com/ether/etherpad-cli-client.git", "ref": "<sha on main>", "kind": "node",    "smokeCmd": "..." },
+  { "name": "etherpad-desktop",    "repo": "https://github.com/ether/etherpad-desktop.git",     "ref": "<sha on main>", "kind": "desktop", "smokeCmd": "..." }
+]
+```
+Refs are pinned to a specific commit SHA (not `main`) so a client's own pushes
+cannot redden core CI; bumping a ref is a deliberate PR. Current `main` HEADs at
+authoring time: pad `31176d6`, cli-client `edbe0bb`, desktop `ad273c1`.
+Pinned refs mean a client's *own* breakage never randomly reddens core; picking up
+a client fix is a deliberate ref-bump PR. Clients are added to the manifest as
+their Phase-2 smoke lands — the workflow only runs what's registered.
+
+### Workflow
+`.github/workflows/downstream-smoke.yml` (triggers: `pull_request` + nightly
+`schedule` against `develop`):
+1. Build core from the PR, install deps.
+2. Boot Etherpad on **:9003** with a known `APIKEY` in the background; record PID.
+3. Healthcheck-poll the server (bounded timeout) before proceeding.
+4. Matrix over manifest entries: clone @ pinned ref → set up toolchain
+   (node+pnpm / rust / electron+xvfb) → copy core's freshly-generated
+   `wire-vectors.json` into the client → run `test:vectors` → run smoke.
+5. Tear down: kill the recorded **PID** (never `pkill -f`).
+
+### Per-client smoke (Phase 2)
+Minimal roundtrip exercising the real protocol end-to-end:
+- **etherpad-pad** (`rust`): integration test gated by `ETHERPAD_SMOKE_URL`, using
+  the real tungstenite socket — connect, open pad, send a changeset, read back
+  via HTTP `getText`, assert. Plus `cargo test` vector consumer reading the
+  injected fixture.
+- **etherpad-cli-client** (`node`): add a minimal test runner (none today —
+  `node:test` or vitest), a `test:vectors` decoding the fixture, and a smoke
+  using the client lib: connect → write → verify via HTTP `getText`.
+- **etherpad-desktop** (`desktop`): **headless-light** vitest smoke that points
+  the shell/webview at the booted URL and roundtrips. The full Electron e2e stays
+  in desktop's own CI — it is **not** in the core gate. If Electron is
+  unavoidable here, run under `xvfb-run`.
+
+## Flakiness mitigations (because smoke runs on every PR)
+
+- Healthcheck-poll-with-timeout before any client runs.
+- Bounded timeout + 1 retry per client smoke.
+- Desktop kept headless-light; heavy Electron e2e excluded from the gate.
+- PID-based teardown, never `pkill -f` (would kill the developer's other servers).
+- Pinned manifest refs isolate core CI from clients' own breakage.
+- Tests that bind a port use **:9003** (9001 is reserved for ad-hoc local use).
+
+## Phasing
+
+- **Phase 1 (core only, lands first, immediately useful):** vector generator +
+  `wire-vectors.json` + three contract specs + `downstream-smoke.yml` +
+  `clients.json` manifest. Harness proven with **one** reference client wired in
+  (the Rust `etherpad-pad`, which already has test infra).
+- **Phase 2 (one client repo at a time):** order `etherpad-pad` →
+  `etherpad-cli-client` → `etherpad-desktop`. Each PR adds that client's
+  `test:vectors` + smoke and registers it in the core manifest.
+
+## Out of scope
+
+- Replacing clients' existing full e2e suites (they stay in their own repos).
+- ep_kaput (excluded from all sweeps per standing instruction).
+- Changing the wire protocol itself — this work only *observes* it.
+
+## Success criteria
+
+- A core PR that alters changeset serialization, the socket message sequence, or a
+  client-facing API shape fails Layer A (contract) and/or Layer B (smoke) before merge.
+- Phase 1 lands green on core `develop` with the Rust client wired into the smoke matrix.
+- Bumping a client's pinned ref is the only way a client's own changes affect core CI.

src/package.json

@@ -154,6 +154,7 @@
     "test-container": "mocha --import=tsx --timeout 30000 --extension ts,js tests/container/specs/api",
     "dev": "cross-env NODE_ENV=development  node --require tsx/cjs node/server.ts",
     "prod": "cross-env NODE_ENV=production node --require tsx/cjs node/server.ts",
+    "vectors:gen": "node --require tsx/cjs tests/backend/specs/downstream/generate-vectors.ts",
     "ts-check": "tsc --noEmit",
     "ts-check:watch": "tsc --noEmit --watch",
     "test-ui": "cross-env NODE_ENV=production npx playwright test",

src/tests/backend/specs/downstream/generate-vectors.ts

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * Single source of truth for the downstream wire-compatibility fixtures.
+ *
+ * Each vector is a self-contained changeset application: given `initialText`
+ * and `pool`, applying `changeset` yields `resultText`. Downstream clients
+ * (which reimplement Etherpad's changeset/attribpool decoders) consume the
+ * exact same JSON and must reproduce `resultText`. See the Phase 1 plan
+ * at docs/superpowers/plans/2026-06-09-downstream-client-compat-tests-phase1.md.
+ *
+ * Runnable as a CLI to (re)write src/tests/fixtures/wire-vectors.json:
+ *   pnpm run vectors:gen
+ */
+
+import * as Changeset from '../../../../static/js/Changeset';
+import AttributePool from '../../../../static/js/AttributePool';
+
+export type WireVector = {
+  name: string;
+  initialText: string;
+  changeset: string;
+  pool: ReturnType<AttributePool['toJsonable']>;
+  resultText: string;
+};
+
+const vector = (
+  name: string,
+  initialText: string,
+  build: (pool: AttributePool) => string,
+): WireVector => {
+  const pool = new AttributePool();
+  const changeset = build(pool);
+  Changeset.checkRep(changeset);
+  return {
+    name,
+    initialText,
+    changeset,
+    pool: pool.toJsonable(),
+    resultText: Changeset.applyToText(changeset, initialText),
+  };
+};
+
+export const generateVectors = (): WireVector[] => [
+  vector('plain-insert', 'abc\n', () =>
+    Changeset.makeSplice('abc\n', 3, 0, 'XYZ')),
+
+  vector('plain-delete', 'abcdef\n', () =>
+    Changeset.makeSplice('abcdef\n', 1, 3, '')),
+
+  vector('formatted-insert', 'abc\n', (pool) =>
+    Changeset.makeSplice('abc\n', 3, 0, 'bold', [['bold', 'true']], pool)),
+
+  vector('multiline-insert', 'abc\n', () =>
+    Changeset.makeSplice('abc\n', 3, 0, 'one\ntwo\n')),
+
+  vector('attrib-reuse', 'abc\n', (pool) => {
+    // Two formatted inserts sharing one pool entry exercises pool index reuse.
+    const cs1 = Changeset.makeSplice('abc\n', 0, 0, 'A', [['bold', 'true']], pool);
+    const mid = Changeset.applyToText(cs1, 'abc\n');
+    const cs2 = Changeset.makeSplice(mid, mid.length - 1, 0, 'B', [['bold', 'true']], pool);
+    return Changeset.compose(cs1, cs2, pool);
+  }),
+];
+
+// CLI entry: write the canonical fixture to disk.
+if (require.main === module) {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const fs = require('fs');
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const path = require('path');
+  const out = path.join(__dirname, '../../../fixtures/wire-vectors.json');
+  fs.mkdirSync(path.dirname(out), {recursive: true});
+  fs.writeFileSync(out, `${JSON.stringify(generateVectors(), null, 2)}\n`);
+  // eslint-disable-next-line no-console
+  console.log(`wrote ${out}`);
+}

src/tests/backend/specs/downstream/wire-http-api.ts

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * Snapshots the *shapes* (keys/types, not volatile values) of the HTTP API
+ * endpoints downstream clients call to create pads and round-trip text.
+ * Auth in the test harness is via JWT (common.generateJWTToken), matching the
+ * rest of the api specs — see api/createDiffHTML.ts.
+ */
+
+const assert = require('assert').strict;
+const common = require('../../common');
+
+describe(__filename, function () {
+  let agent: any;
+  let apiVersion = 1;
+  const padId = `wireHttp_${common.randomString()}`;
+  const endPoint = (point: string) => `/api/${apiVersion}/${point}`;
+
+  before(async function () {
+    agent = await common.init();
+    const res = await agent.get('/api/').expect(200).expect('Content-Type', /json/);
+    apiVersion = res.body.currentVersion;
+    assert(apiVersion);
+  });
+
+  it('createPad returns the standard {code,data,message} envelope', async function () {
+    const res = await agent.get(`${endPoint('createPad')}?padID=${padId}&text=hello%0A`)
+        .set('Authorization', await common.generateJWTToken())
+        .expect(200);
+    assert.deepEqual(Object.keys(res.body).sort(), ['code', 'data', 'message']);
+    assert.equal(res.body.code, 0);
+  });
+
+  it('setText + getText round-trips text through the documented shape', async function () {
+    await agent.post(endPoint('setText'))
+        .set('Authorization', await common.generateJWTToken())
+        .send({padID: padId, text: 'world\n'})
+        .expect(200);
+    const res = await agent.get(`${endPoint('getText')}?padID=${padId}`)
+        .set('Authorization', await common.generateJWTToken())
+        .expect(200);
+    assert.equal(res.body.code, 0);
+    assert.equal(typeof res.body.data.text, 'string');
+    assert.equal(res.body.data.text, 'world\n');
+  });
+
+  it('getRevisionsCount exposes a numeric revisions field', async function () {
+    const res = await agent.get(`${endPoint('getRevisionsCount')}?padID=${padId}`)
+        .set('Authorization', await common.generateJWTToken())
+        .expect(200);
+    assert.equal(res.body.code, 0);
+    assert.equal(typeof res.body.data.revisions, 'number');
+  });
+});

src/tests/backend/specs/downstream/wire-socket-sequence.ts

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * Pins the socket.io message sequence + shapes that every realtime client
+ * depends on: handshake -> CLIENT_VARS, then USER_CHANGES -> ACCEPT_COMMIT.
+ * A change here is a wire-protocol change that will break downstream clients
+ * (the Rust terminal editor and the Node CLI both speak this sequence by hand).
+ */
+
+const assert = require('assert').strict;
+const common = require('../../common');
+const padManager = require('../../../../node/db/PadManager');
+
+describe(__filename, function () {
+  let agent: any;
+  let socket: any;
+  let pad: any;
+  let padId: string;
+
+  before(async function () { agent = await common.init(); });
+
+  beforeEach(async function () {
+    padId = common.randomString();
+    pad = await padManager.getPad(padId, 'dummy\n');
+    await pad.setText('\n'); // ensure the pad exists at a known empty state
+    const res = await agent.get(`/p/${padId}`).expect(200);
+    socket = await common.connect(res);
+  });
+
+  afterEach(async function () {
+    if (socket != null) socket.close();
+    socket = null;
+    if (pad != null) await pad.remove();
+    pad = null;
+  });
+
+  it('handshake returns CLIENT_VARS with the client-facing shape', async function () {
+    const {type, data} = await common.handshake(socket, padId);
+    assert.equal(type, 'CLIENT_VARS');
+    assert.ok(data.userId, 'CLIENT_VARS.userId missing');
+    assert.ok(data.collab_client_vars, 'collab_client_vars missing');
+    assert.equal(typeof data.collab_client_vars.rev, 'number');
+    assert.ok(data.collab_client_vars.initialAttributedText,
+      'collab_client_vars.initialAttributedText missing');
+  });
+
+  it('USER_CHANGES is acknowledged with ACCEPT_COMMIT and a bumped rev', async function () {
+    const {data: clientVars} = await common.handshake(socket, padId);
+    const rev = clientVars.collab_client_vars.rev;
+    const authorId = clientVars.userId;
+    // Insert ops must carry the session author attribute (`*0+N` + matching
+    // apool entry) or the server rejects with {disconnect:'badChangeset'}.
+    const apool = {numToAttrib: {0: ['author', authorId]}, nextNum: 1};
+    await Promise.all([
+      common.waitForAcceptCommit(socket, rev + 1),
+      common.sendUserChanges(socket, {baseRev: rev, changeset: 'Z:1>5*0+5$hello', apool}),
+    ]);
+    assert.equal(pad.text(), 'hello\n');
+  });
+});

src/tests/backend/specs/downstream/wire-vectors.ts

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Guards the downstream wire-format contract:
+ *  - the committed fixture exactly matches a fresh regeneration (any drift is a
+ *    deliberate wire change and must be re-generated + reviewed in the same PR), and
+ *  - every vector is internally consistent under core's own Changeset engine.
+ */
+
+const assert = require('assert').strict;
+import fs from 'fs';
+import path from 'path';
+import * as Changeset from '../../../../static/js/Changeset';
+import {generateVectors} from './generate-vectors';
+
+const fixturePath = path.join(__dirname, '../../../fixtures/wire-vectors.json');
+
+describe(__filename, function () {
+  it('committed fixture matches a fresh regeneration', function () {
+    const committed = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+    const fresh = generateVectors();
+    assert.deepEqual(committed, fresh,
+      'wire-vectors.json is stale — run `pnpm run vectors:gen` and commit the result');
+  });
+
+  it('every vector applies to its result under core Changeset', function () {
+    for (const v of generateVectors()) {
+      Changeset.checkRep(v.changeset);
+      assert.equal(Changeset.applyToText(v.changeset, v.initialText), v.resultText,
+        `vector ${v.name} result mismatch`);
+    }
+  });
+});

src/tests/downstream/clients.json

@@ -0,0 +1,29 @@
+[
+  {
+    "name": "etherpad-pad",
+    "repo": "https://github.com/ether/pad.git",
+    "ref": "31176d64ce746d45349e58ee6c0bb043052c6e66",
+    "kind": "rust",
+    "enabled": false,
+    "vectorTest": "cargo test --test vectors",
+    "smokeCmd": "cargo test --test smoke -- --ignored"
+  },
+  {
+    "name": "etherpad-cli-client",
+    "repo": "https://github.com/ether/etherpad-cli-client.git",
+    "ref": "edbe0bb70971e54514ebea672e4ad9b51fc55bff",
+    "kind": "node",
+    "enabled": false,
+    "vectorTest": "pnpm run test:vectors",
+    "smokeCmd": "pnpm run test:smoke"
+  },
+  {
+    "name": "etherpad-desktop",
+    "repo": "https://github.com/ether/etherpad-desktop.git",
+    "ref": "ad273c119f1926a8390c9908fc91f62fa2cf740f",
+    "kind": "desktop",
+    "enabled": false,
+    "vectorTest": "pnpm run test:vectors",
+    "smokeCmd": "pnpm run test:smoke"
+  }
+]

src/tests/fixtures/wire-vectors.json

@@ -0,0 +1,62 @@
+[
+  {
+    "name": "plain-insert",
+    "initialText": "abc\n",
+    "changeset": "Z:4>3=3+3$XYZ",
+    "pool": {
+      "numToAttrib": {},
+      "nextNum": 0
+    },
+    "resultText": "abcXYZ\n"
+  },
+  {
+    "name": "plain-delete",
+    "initialText": "abcdef\n",
+    "changeset": "Z:7<3=1-3$",
+    "pool": {
+      "numToAttrib": {},
+      "nextNum": 0
+    },
+    "resultText": "aef\n"
+  },
+  {
+    "name": "formatted-insert",
+    "initialText": "abc\n",
+    "changeset": "Z:4>4=3*0+4$bold",
+    "pool": {
+      "numToAttrib": {
+        "0": [
+          "bold",
+          "true"
+        ]
+      },
+      "nextNum": 1
+    },
+    "resultText": "abcbold\n"
+  },
+  {
+    "name": "multiline-insert",
+    "initialText": "abc\n",
+    "changeset": "Z:4>8=3|2+8$one\ntwo\n",
+    "pool": {
+      "numToAttrib": {},
+      "nextNum": 0
+    },
+    "resultText": "abcone\ntwo\n\n"
+  },
+  {
+    "name": "attrib-reuse",
+    "initialText": "abc\n",
+    "changeset": "Z:4>2*0+1=3*0+1$AB",
+    "pool": {
+      "numToAttrib": {
+        "0": [
+          "bold",
+          "true"
+        ]
+      },
+      "nextNum": 1
+    },
+    "resultText": "AabcB\n"
+  }
+]