DreamLake

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:

json
{ "commandId": "cmd-conformance-0001" }

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:

json
{ "note": "…", "hash": "sha256:…", "revision": "rtc:…", "baseRevision": "rtc:…",
  "mode": "merge", "outcome": "accepted", "commandId": null, "replayed": false }
FieldMeaning
outcomeaccepted — the native batch was acknowledged. no-write — the compiled edit set was empty; revision/hash are what the server observed, nothing was committed.
commandIdEcho of the request, null when none was sent.
replayedtrue 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

StateSet whenA call with the same id and fingerprint gets
pendingThe unique-index insert succeeded; the commit is running409 command_in_progress
acceptedThe room acknowledged the batch; receipt stored verbatim200, the stored receipt with replayed: true; nothing is read, compiled or committed
no-writeEmpty edit set; current revision observedsame as accepted
unknownA native request was sent and nothing definitive came back409 command_outcome_unknown; the id is never re-run

Order of operations on a write with commandId:

  1. Request validation (428, 412, 400) exactly as before.
  2. Lookup, before any baseline read or RTC work: a completed command answers from its record; a different fingerprint is 409 command_intent_mismatch whatever the state.
  3. Baseline read, patch parse (422), then the claim — the insert on the unique key. A duplicate-key loser is 409 command_in_progress.
  4. Commit. A deterministic refusal (412 stale/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 sets unknown; the 503 body carries the commandId.
  5. 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

GET /namespaces/:ns/notes/:noteId/commands/:commandId
→ 200 { commandId, state, outcome?, receipt?, error?, createdAt, updatedAt }
→ 404 { error: "command_not_found" }

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

StatuserrorWhen
409command_in_progressAnother request holds the claim
409command_intent_mismatchSame id, different patch, baseline, mode or format
409command_outcome_unknownA native commit may have been sent; query status, read the memo, decide
403forbiddencommandId without an authenticated actor
404command_not_foundNo 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: commandId is 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.