Sanity-check metadata ordering so incoherent transitions do not read as ordinary conflicts

[ElliotDrel]

Follow-up from #87, criterion 2

#87's second acceptance criterion asked for two things: a useful proposed-vs-current diff on genuine conflicts, and a sanity check on metadata ordering. The diff half shipped and is tested (docsChangePrecision.js:471-488, replaceDocumentWithMarkdown.js:298-329, covered by docsChangePrecision.test.js:258-279 and replaceDocumentCollateral.test.js:209-225).

The ordering check was never built. Nothing in the guard treats an impossible metadata transition as suspicious rather than as a genuine conflict.

What is missing

guardMutation compares a stored modifiedTime against the current one and treats "different" as "changed". It does not ask whether the difference is coherent:

• A modifiedTime that moves backwards from the recorded read is not a normal edit. It means a clock skew, a Drive metadata quirk, or state from a different file, and reporting it as "modified externally since you last read it" sends the user to re-read a document that may not have changed.
• A revision id that goes backwards, or that is unchanged while modifiedTime moved by a large margin, is similarly incoherent.

Today all of these produce the same generic staleness rejection, so a real bug in our own bookkeeping is indistinguishable from an ordinary concurrent edit.

Required outcome

• Detect metadata transitions that cannot happen under normal Drive/Docs behavior.
• Report them distinctly from a genuine conflict, so the message tells the user what actually happened rather than sending them to re-read.
• Keep failing closed. An incoherent transition must not be treated as "probably fine, allow the write".
• Cover it with tests that assert the incoherent case produces its own message, not the standard staleness text.

Context

Split out of #87 rather than holding that master issue open. The read-before-write guard is otherwise complete and verified: see the criterion-by-criterion acceptance check at #87 (comment).

Not a 3.0.0 blocker. The guard is correct today, just not maximally informative when its own inputs are nonsense.

[ElliotDrel]

Triage note from the pre-publish review (2026-09-02): out of scope for the upcoming release, staying open. This is the "distinct message for an incoherent transition" half; the guard is correct and fails closed without it. Two things worth having in hand before anyone picks it up:

Part of the backwards case is already handled. dist/readTracker.js guardMutation has modifiedTimeWentBackwards() (landed for #119): when Drive reports a modifiedTime strictly earlier than the one the last read recorded (a lagging replica), it keeps the newer baseline, logs the observation, and lets the write proceed under the downstream writeControl.requiredRevisionId guard instead of reporting "modified externally". So a backwards timestamp no longer produces the generic staleness message; what is missing is the rest of the list in this issue (revision going backwards, and the mismatch cases) plus the distinct user-facing wording.

One transition on the list is coherent, not incoherent. Measured live today while fixing #144: every comment write (addComment, replyToComment, updateComment, resolveComment, deleteComment) advances the Docs revisionId while Drive modifiedTime stays byte-identical (version bumps, modifiedTime does not). So "revision moved, timestamp did not" is normal Drive behaviour for comment activity and must not be classified as suspicious. The reverse ("timestamp moved by a large margin, revision unchanged") is still a fair candidate. Whoever builds the sanity check should assert the comment case stays a plain revision conflict (or, after #144, no conflict at all when the comment came from this process).