A write should not cost a revision

Every body change snapshotted into history — core/src/local/store.rs and
notes/__init__.py both — so a write was expensive, and the clients
compensated by writing as rarely as they could. BoardViewModel says it
outright: "Saved on close rather than per keystroke, so a session of typing
costs one write and one revision snapshot."

That is durability paying for version history. An app kill mid-session lost
everything typed, so that the revision list would stay tidy. The safety
property is worth more than the feature it was subsidising, and no
comparable product makes this trade: Keep and Apple Notes write
continuously with no history, Docs and Notion write continuously and
coalesce history behind the scenes, Obsidian debounces and snapshots on an
interval. Save-on-close is the outlier, and this coupling is why we had it.

A body change now earns a snapshot only if it is the first of an editing
session — the body actually differs, and the note carries no revision from
the last ten minutes.

Session granularity falls out of the window rather than being declared. A
snapshot stores the body as it was BEFORE the edit, so the first write of a
sitting captures the note as you found it and every write after it inside
the window adds nothing. One revision per sitting, with no commit flag for
a client to send and no wire surface to carry it.

That is why it is a time rule and not a protocol one. sync.py applies pushed
bodies through the same check, so a client autosaving every second cannot
make the server snapshot every second either — which a client-declared
commit point could not have guaranteed without a protocol bump.

Restoring a revision still snapshots unconditionally: a considered act, not
a keystroke, and it stays undoable.

Unblocks idle-debounced autosave, an honest updated_at, and the "Edited just
now" line the editor is getting.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/thoughtsync/notes/__init__.py

@@ -34,6 +34,7 @@ from ..models.note_attachment import NoteAttachment
 from ..models.note_item import NoteItem
 from ..models.note_link_preview import NoteLinkPreview
 from ..models.note_revision import NoteRevision
+from ..revisions import should_snapshot
 from ..responses import json_error, not_found, parse_uuid
 from ..retention import purge_note
 from ..settings import get_setting
@@ -485,8 +486,10 @@ async def update_note(note_id: str):
         if "body" in data:
             note.display_title = await _name_for(db, note)
             await _reconcile_tags(db, note)
-        # Version history: snapshot the PRE-edit body whenever it changed.
-        if note.body != old_body:
+        # Version history: snapshot the PRE-edit body, once per editing session
+        # rather than once per write — see revisions.should_snapshot. Writing often
+        # is what lets a client autosave instead of hoarding text until it closes.
+        if await should_snapshot(db, note.id, old_body, note.body):
             db.add(NoteRevision(note_id=note.id, body=old_body))
         await db.commit()
         await db.refresh(note)

src/thoughtsync/revisions.py

@@ -0,0 +1,55 @@
+"""When a body change is worth keeping a version of.
+
+A note's body used to snapshot into `note_revisions` on EVERY write, which made a
+write expensive — and the clients compensated by writing as rarely as they could
+get away with, saving only when an editor closed. That is durability paying for
+version history: a crash mid-session lost everything typed, so that the revision
+list would stay tidy. The safety property is worth more than the feature it was
+subsidising.
+
+The rule here breaks that trade. A body change earns a snapshot only if it is the
+first one of an editing session, so a client may write as often as it likes.
+
+Session granularity falls out of the window rather than being declared. A snapshot
+stores the body as it was BEFORE the edit, so the first write of a sitting captures
+the note as you found it and every write after it inside the window adds nothing —
+one revision per sitting, with no "commit" flag for a client to send and no wire
+surface to carry it. That last part is why this is a time rule and not a protocol
+one: `sync.py` applies pushed bodies through the same check, so a client autosaving
+every second cannot make the server snapshot every second either.
+
+Deliberately NOT applied to restoring a revision. That is a considered act rather
+than a keystroke, and it snapshots unconditionally so restoring is itself undoable.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import select
+
+from .models.note_revision import NoteRevision
+
+# How long one editing session is assumed to last. A constant rather than a setting:
+# it is not a preference anyone holds, and the value only has to be longer than a
+# sitting and shorter than the gap between two of them. Promote it to the settings
+# registry (rule 25) if that ever stops being true.
+REVISION_WINDOW_MINUTES = 10
+
+
+async def should_snapshot(db, note_id: uuid.UUID, old_body: str, new_body: str) -> bool:
+    """Whether `old_body` should be kept as a revision before `new_body` replaces it.
+
+    False when the text did not actually change — re-saving identical bytes is not a
+    version of anything — and False when this note already has a revision from the
+    current session.
+    """
+    if old_body == new_body:
+        return False
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=REVISION_WINDOW_MINUTES)
+    recent = await db.scalar(
+        select(NoteRevision.id)
+        .where(NoteRevision.note_id == note_id, NoteRevision.created_at >= cutoff)
+        .limit(1)
+    )
+    return recent is None

src/thoughtsync/sync.py

@@ -26,6 +26,7 @@ from .models.label import Label, NoteLabel
 from .models.note import Note
 from .models.note_item import NoteItem
 from .models.note_revision import NoteRevision
+from .revisions import should_snapshot
 from .notes import (
     _reconcile_tags,
     _serialize_notes,
@@ -317,8 +318,13 @@ async def _apply_note(db, ch: dict) -> dict:
     note.display_title = derive_display_title(note.body, _first_item_text(ch))
     if edited_at is not None:
         note.updated_at = edited_at
-    # Non-destructive LWW: snapshot the overwritten server body into history.
-    if not creating and note.body != old_body:
+    # Non-destructive LWW: snapshot the overwritten server body into history —
+    # subject to the same session window as a direct edit (revisions.should_snapshot).
+    # This path is why the window is a time rule rather than a flag on the wire: a
+    # client autosaving every second pushes a body change every second, and without
+    # the check the SERVER would snapshot each one no matter how restrained the
+    # client's own store was being.
+    if not creating and await should_snapshot(db, note.id, old_body, note.body):
         db.add(NoteRevision(note_id=note.id, body=old_body))
     await db.flush()  # assign note.id before items/labels/links
     await _apply_note_items(db, note, ch)