test(server): Postgres concurrency harness — make the write races observable (CWD-11)

[eliotlim]

Problem

Every server test runs on PGlite, whose Mutex serializes all store calls — no existing test can observe a lost update. The write races the Concurrency & Write Durability epic (OB-76) fixes only manifest on real Postgres (MVCC + pool), so the epic needed a harness that makes them reproducible before any fix can be proven. Board: CWD-11.

Solution

A dedicated real-Postgres suite (*.pg.ts, own vitest config, excluded from the default runner both directions) with: barrier/start-gate interleaving primitives (participant-keyed rendezvous with deadline — a hung barrier or dead server surfaces as a loud harness fault, never as a false "race reproduced"); three test.fails baseline races documenting today's live bugs (updateRow blob clobber, instance-config lost key, setPageProperties interleaving — each tagged with the CWD issue that flips it); scratch-DB-per-test provisioning with fault-tolerant teardown; a runner preflight that proves the target is a real Postgres with CREATE DATABASE rights (born of a week-long hunt for a stale process squatting the harness port); and a PR-gating CI job with a Postgres service container.
Key files: packages/server/src/postgresConcurrency.pg.ts, src/testUtils/concurrency.ts, scripts/test-pg.mjs, docker-compose.test-pg.yml, .github/workflows/ci.yml. New deps: none.

Before / After

No visual change — test infrastructure.

Behavior	Before	After
Write races under concurrency	Invisible (PGlite mutex serializes)	Reproduce deterministically: 3 expected fail documents each live race
Race fixed by CWD-2/3/4	No proof possible	Flip test.fails→test (flip obligations documented at each site)
Harness infra failure (hung barrier, dead/squatted DB)	n/a	Loud red: rendezvous deadline + fault sentinel + runner preflight (each adversarially verified)
CI	No real-Postgres concurrency coverage	Postgres concurrency (write races) job, service container, ~2s suite

Test procedure

docker compose -f docker-compose.test-pg.yml up -d --wait   # or docker run postgres:16.9-alpine -p 55432:5432
OPENBOOK_TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:55432/postgres \
OPENBOOK_REQUIRE_CONCURRENCY_PG=1 pnpm --filter @book.dev/server test:pg
# expected: 3 passed | 3 expected fail (6), exit 0

Operational notes

• Owner action: add Postgres concurrency (write races) to branch protection's required contexts — auto-merge fires on fast checks, so an unrequired job can be bypassed.
• Merge order: this before CWD-3 (fix(server): updateRow per-key merge + updateInstanceConfig transaction (CWD-3) #322); CWD-3 then flips its two races per the in-file flip comments.
• Default pnpm verify is untouched (PGlite-only); the pg suite runs only with the env var.

---

Verify: green (full pnpm verify; one unrelated backupBoot flake ruled out by isolated rerun — tracked as INF-3). Real-Postgres leg: 3 passed | 3 expected fail, exit 0, adversarially probed (hung-barrier, dead-port, and mid-run-kill scenarios all fail loud). Reviews cleared: code (Quinn — 2 rounds incl. empirical mutation/flip probes; final endorsement on the F6/F7 diff).

🤖 Generated with Claude Code

https://claude.ai/code/session_018RUicirLRuuZvjJN13N6yN

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app.book.pub	Ready	Preview	Aug 14, 2026 2:49pm