ADR-0090: Undo coalescing by word, decided in the core

Status: Accepted
Date: 2026-09-10
Deciders: jka
Decision: D90

Context

Every keystroke was its own undo step, so undoing a typed word took one undo per letter. Grouping had been planned from the start. The questions were where the grouping is decided and what the unit is.

Decision

Grouping is decided in the core, in rio::doc::edit, the single path every edit takes. The undo history belongs to the core (ADR-0003), so every frontend gets the behaviour with no view change, and undoing a group emits one buffer.changed.

The rule is word granularity:

A new edit merges into the top undo record if it is a single character that continues it: typing forwards at the end of the run, Backspace immediately before its start, or Delete repeated at the same position.
A run ends after a blank character joins it, so "the " and "quick " are separate steps.
A newline never joins a run.
Anything else (a paste, typing over a selection, Replace All, an agent edit, any multi-character edit) is its own step and closes the run.

The core uses neither a clock nor the caret. A run continues only while edits are adjacent, so moving the caret and typing elsewhere ends it without the frontend reporting cursor moves (ADR-0022).

buffer.replace accepts an optional coalesce flag, default on. A frontend sends 0 for a discrete command, meaning "start a new step here". The flag breaks the run before the edit, and the new step can still grow. The vi extension sets it on every normal-mode and visual-mode key, so repeated x or dd are separate undo steps while i followed by typing is one.

Alternatives considered

Whole-run grouping as in vim. The maintainer chose word granularity.
An idle timeout that ends a run. Rejected for now because it makes the model time-dependent; it could be added later without changing the protocol.

Consequences

Undo behaves as users expect, in every frontend.
Two identical single-character deletions are indistinguishable to the core; only the frontend knows whether they were one gesture, hence the coalesce flag.
A reload of a changed file is always its own undo step (ADR-0094).