RFC: should a burst of connected-app writes wait instead of failing busy? #360

Parent

#328. Related: #229, #329.

Question

A burst of writes to one cold document can answer busy and apply nothing. Should it wait instead? Decide from production data first.

Acceptance

• On or after 2026-10-12, the maintainer posts sum(increase(document_content_apply_total{outcome="busy"}[14d])). Also post the same query filtered to mode=~"blocks|text", which is MCP only.
• If the count is small, close this issue as not planned. Today's text already says "Retry in a few seconds." (writeResult in documentTools.ts)
• If the count is not small, post one ruling: A (name the wait in the tool text and in docs/mcp/reference.md §Limits), B (retry once inside the tool), or C (keep a cold room loaded briefly). Open a new issue for B or C.

Facts

• withDocumentLock and WS_APPLY_DEADLINE_MS (20 s) live in hocuspocusApply.ts and types.ts.
• Production runs two hocuspocus-server replicas. Each has its own lock, so a one-process local burst does not predict production.
• Raising the deadline gains little: it must stay below the 30 s hop timeout.
• A busy refusal is counted only as tool-error today. If the ruling is A, reuse the outcome argument that Refuse a connected-app rewrite of a section that holds media #329 adds to refuse() to count busy apart.

Out of scope

Any change to the #229 lock before the ruling.