docs(sdk,server): durable-write contract — rev CAS, WriteError taxonomy, Idempotency-Key (CWD-1)

[eliotlim]

Problem

The Concurrency & Write Durability epic (OB-76) needs one contract that CWD-2 (server CAS), CWD-5 (idempotency), CWD-6 (client chokepoint), CWD-7 (IndexedDB outbox) and CWD-10 (conflict UX) can build against without re-deriving semantics — today the SDK has no typed write errors, no version tokens, and idempotency covers 1 of ~25 write routes. Board: CWD-1.

Solution

docs/write-contract.md (normative spec) + exported TS types in @book.dev/sdk (+ server envelope aliases). No runtime behavior change — types ship unused until CWD-2/5/6 land. Key decisions (owner-ratified): opt-in expectedRev CAS (legacy callers keep LWW); rev naming to avoid permanent collision with page version history; per-entity revs with T9 persister checkpoints incrementing; discriminated 409 conflict envelopes carrying permission-filtered current state; Idempotency-Key with request fingerprinting, response-capture ledger, 7-day GC, and a server capability flag gating outbox auto-replay; stable-position ordering contract (implementation = CWD-12).
Survived two adversarial review rounds (Quinn: 20 findings round 1, 12 round 2 — all resolved; four semantics calls escalated to owner and baked in).

Before / After

No visual change — docs + types only.

Surface	Before	After
Write failure semantics	Untyped Error from throwIfNotOk; 1 typed case (401 getPage)	10-class WriteError taxonomy with retryable, spec'd per status
Concurrency control	None (pure LWW everywhere)	Opt-in expectedRev + 409 conflict envelope contract
Idempotency	Keyless page-create ledger only	Idempotency-Key header contract for all wave-1 routes + replay semantics
SDK exports	—	New types compile-checked in sdk build (pnpm --filter @book.dev/sdk build)

Test procedure

pnpm --filter @book.dev/sdk build && pnpm --filter @book.dev/server typecheck
pnpm verify

Operational notes

None now (docs/types only). Downstream consequences are tracked per-issue on the board: CWD-2 carries the instance-config TOCTOU + null-semantics alignment criteria; CWD-12 owns the ordering migration (must preserve the ledger posting-order hash + numeric-position bundle import).

---

Verify: green (full pnpm verify ×2 on final tip). Reviews cleared: code (Quinn — 2 rounds, final 12 findings all pre-endorsed and applied; re-verify confirmed downstream may build unchanged).

🤖 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:02pm