Fix the lost content write, then add the MCP write tools

[HMarzban]

Problem

Concurrent writes to PATCH /api/documents/:documentId/content are silently lost. Measured against a running stack: five parallel calls, each a full replace.

HTTP 200/200/200/200/200  ->  ["Title","N3"]

All five callers were told they succeeded. Four writes were discarded. There is no version check, no precondition and no conflict code.

Overlapping writes can also corrupt the document shape. Two trials of three produced two level-1 headings:

trial 1: 200/200 -> ["Title","pre1","Title","Y1"]
trial 2: 200/200 -> ["Title","Y2","Title","pre2"]

mode: replace stopped replacing. The server itself refuses that shape on input with 422 document content must start with a level-1 heading. So the write path can produce a document the read path would reject, and the damage survives export.

Held to a narrow claim: two clean concurrent writes never corrupted across three trials. They only lost one write each. Corruption needs an in-flight overlap; the lost update needs only concurrency.

A person rarely triggers this. An agent triggers it constantly, because it retries and runs in parallel.

What to do

Fix the lost update first. Then, and only then, add the MCP write tools.

The order is not negotiable. Shipping a write tool onto a write path that silently discards work turns one defect into many documents.

Acceptance

• Five parallel PATCH .../content calls no longer end with four writes discarded. Either they serialize, or a losing caller receives a conflict.
• A caller can tell a successful write from a discarded one, from the response alone.
• After the fix, the MCP write tools ship.

Notes

The write path is apps/hocuspocus.server/src/modules/document-content/. domain/applyContentToDoc.ts performs the replace, and infra/hocuspocusApply.ts runs the flush that returns before the version row is written.

Related to the open write-model questions: a write precondition (#161) and what a PATCH should return so a caller can confirm the write (#164).

The 200 is not durable either. The store flush is synchronous, but it enqueues, and the version row is written by the BullMQ worker afterwards.

replace is idempotent at document level, so a plain retry of a single write is already safe. The defect is concurrency, not retry.

Blocked by #226.

[HMarzban]

The root cause is not concurrency.

• Each content apply closes its direct connection, and the room unloads. The next apply loads
  the Postgres head before the worker has written the previous write. The worker then merges both
  states, so replace behaves like append.
• Plain sequential writes reproduce it: 3 of 3 trials ended with two level-1 headings.
• Five parallel writes on one process ended clean, with one body. That is normal replace.

Fix: a per-document lock, plus a wait until a head row covers the write's state vector, bounded
at 20 s. On timeout the route answers 503 SAVE_NOT_CONFIRMED, never a false 200. The 200
carries version. A regression test fails without the fix and passes with it. The MCP write tools
ship on top. Not deployed yet.

[HMarzban]

The per-document lock and the commit wait shipped in f2682d675, with a regression test. The MCP write tools followed in c68d53947 and deployed on 2026-09-28. A cold 200 now carries version, and an unconfirmed save answers 503 SAVE_NOT_CONFIRMED. The lock holds within one process, and production runs two collab replicas. The cross-replica test moved to #381.