RFC: what should a content PATCH return so a caller can confirm its write? #164

Problem

A successful PATCH /api/documents/:documentId/content returns { documentId, mode }. A caller cannot tell which stored revision its write produced, so a retry is blind.

No revision number exists when the response is written. The cause is the background worker, not the save debounce:

• The apply runs inside a transaction on the live document.
• The store hook then flushes immediately, because the direct connection closes in a finally before the response returns. The ten-second and sixty-second debounce figures cover browser edits only.
• That flush enqueues the snapshot. A background worker mints the revision row afterwards.
• The one code path that computes a number inline is the queue-down fallback, not the normal path.

Four cases break any predicted number:

• Identical bytes deduplicate through the store job id, so no row is minted.
• A concurrent live edit mints a second row, so the count moves by two.
• A revision collision drops the flush.
• An append into a draft returns before any row is written.

What to decide

One of three response bodies:

1. The head revision as it stood before the apply. Honest, and always available.
2. version: null, with a documented meaning.
3. No version field, and documentation that says why.

Acceptance

• One option is chosen.
• apps/hocuspocus.server/API.md documents what the returned value means.

Notes

Threading a number through the REST-to-collaboration hop touches six files under apps/hocuspocus.server/src/modules/document-content/, not two.

API.md already tells callers to confirm a write by reading GET /content back. That guidance stays correct whichever option is chosen.