Memos command identity
2026-10-30 — Phase 1 server contract
A REST retry used to be a new operation: commitNativeNote minted a fresh
request identity per HTTP call, so a response lost after the commit left the
caller unable to recover its receipt, and a resend could land twice. This is
the "public retry identity" gap of the RTC protocol audit
(:note[6ae3ad979f3399f86d9723f1]). The server side of Phase 1 closes it with a
caller-stable command identity on the v2 body mutation. Legacy diff/ETag
requests are untouched.
Request and receipt
PATCH /namespaces/:ns/notes/:noteId/body with the v2 shape
(format, patch, baseRevision, optional mode) accepts one optional field:
8–128 characters from [A-Za-z0-9._:-], validated in the JSON schema. The body
is additionalProperties: false, so a server without this feature answers 400:
capability detection is the echo, and a client that sent an id must find it in
the receipt.
Every v2 receipt now carries three more fields, with or without a commandId:
| Field | Meaning |
|---|---|
outcome | accepted — the native batch was acknowledged. no-write — the compiled edit set was empty; revision/hash are what the server observed, nothing was committed. |
commandId | Echo of the request, null when none was sent. |
replayed | true only when the receipt came from the stored record of an earlier call. |
Fingerprint and scope
The fingerprint is sha256 of the canonical JSON
{"noteId","baseRevision","mode","format","patchHash"} (keys in that order, no
whitespace), where patchHash = sha256(patch UTF-8) and mode is the
effective mode — exact when mode: "exact" or If-Match is sent, otherwise
merge. The actor is not part of the fingerprint; authorization is re-checked
on every call and the record is scoped (noteId, actorId, commandId), the same
scoping as the attachment journal. Two users cannot collide on an id or read
each other's receipts.
States and flow
| State | Set when | A call with the same id and fingerprint gets |
|---|---|---|
pending | The unique-index insert succeeded; the commit is running | 409 command_in_progress |
accepted | The room acknowledged the batch; receipt stored verbatim | 200, the stored receipt with replayed: true; nothing is read, compiled or committed |
no-write | Empty edit set; current revision observed | same as accepted |
unknown | A native request was sent and nothing definitive came back | 409 command_outcome_unknown; the id is never re-run |
Order of operations on a write with commandId:
- Request validation (
428,412,400) exactly as before. - Lookup, before any baseline read or RTC work: a completed command answers
from its record; a different fingerprint is
409 command_intent_mismatchwhatever the state. - Baseline read, patch parse (
422), then the claim — the insert on the unique key. A duplicate-key loser is409 command_in_progress. - Commit. A deterministic refusal (
412stale/overlap,422, an RTC outage before any send) deletes the pending row: a corrected retry with the same id is a new command. A sent-and-unsettled commit setsunknown; the503body carries thecommandId. - The receipt is stored and the row settled; a failed record write never turns an acknowledged write into an error for the caller.
Uncertainty is stated by the commit path rather than guessed by the route:
commitConditionalNote and commitNativeNote tag an error only after the
frozen request was sent and the reply was neither an acceptance nor a definitive
refusal — including a lost-ACK replay that also settled nothing. A failure after
the room acknowledged is treated the same way (the write happened, the receipt
was lost).
A pending row older than five minutes was abandoned by a process that never
reported back. The next call or status read flips it to unknown instead of
answering command_in_progress forever; a late settle from the original
process still wins, because the acknowledgement is the truth.
Status endpoint
Same authorization as the body write (read-only callers get 403, invisible
memos 404), scoped to the calling actor. receipt is present for accepted
and no-write and is the stored receipt (replayed: false); error is present
for unknown and names the status, code and message the write returned.
Error codes
| Status | error | When |
|---|---|---|
| 409 | command_in_progress | Another request holds the claim |
| 409 | command_intent_mismatch | Same id, different patch, baseline, mode or format |
| 409 | command_outcome_unknown | A native commit may have been sent; query status, read the memo, decide |
| 403 | forbidden | commandId without an authenticated actor |
| 404 | command_not_found | No record for this actor, or an id outside the charset |
Storage and deployment
New Prisma model NoteCommand with @@unique([noteId, actorId, commandId]),
no TTL and no data migration. The deploy preflight proposes
NoteCommand_noteId_actorId_commandId_key as an index addition and refuses to
create it during a deploy; apply it through the schema-indexes workflow (scope
all, plan then apply) before shipping the route. Without the index the claim
is not atomic.
Not covered here
- An epoch/generation per mutation on the native wire, and identity-scoped preconditions that would let merge mode stop being a global revision CAS — protocol extensions, see findings 2 and 3 of the audit.
- Automatic reconciliation of
unknown: proving acceptance from the retained RTC journal would need the frozen request identity to be persisted with the row and matched against the room's history. Not done; the state is honest and the id is never re-run. - Client defaults:
commandIdis opt-in in this phase. Flipping clients to always generate one follows the server deployment.
Validation: pnpm exec tsc --noEmit, and vitest on
src/services/notesCommandIdentity.test.ts, notesV2Routes.test.ts,
notesConditionalRtc.test.ts, notesNativeRtc.test.ts and
src/deployment/schemaIndexes.test.ts. Not deployed; no production evidence.