logseq/docs/adr/0001-undo-redo-worker-sync.md

ADR 0001: Undo/Redo scoped to local changes in worker sync

Date: 2026-01-28 Status: Accepted

Context

The worker-based db-sync flow applies remote updates directly to the local DB. Undo/redo must remain usable for the current user without replaying or reverting server changes. The system already supports tx-meta flags (e.g., :local-tx?, :gen-undo-ops?, :undo?, :redo?) and has conflict checks in undo logic.

We must ensure undo/redo never attempts a transaction that would result in invalid client or server data. We also want a simple, sane model that avoids tracking per-remote update history.

Constraints and goals:

• No server echo of the user's own txs back to the same client.
• Best effort undo: if conflicts make an undo unsafe, skip it and keep data valid (never force invalid data).
• Remote updates must not create undo history.
• Local updates must create undo history as before.

Decision

1. Only local txs may generate undo/redo ops. A tx is local if and only if tx-meta contains :local-tx? true.
2. All remote/apply/rebase/import paths must set :local-tx? false and :gen-undo-ops? false.
3. Undo/redo will be "best effort": if reversing a tx would violate invariants (e.g., moved block, deleted parent, remaining children), the undo op is dropped and history is cleared for that repo to prevent invalid data.

This keeps undo/redo stable and ensures remote updates never appear in the user's undo stack.

Architecture

Source of truth for origin

• :local-tx? is the sole origin flag.
• Local changes (UI/outliner ops) attach :local-tx? true at the time of submission to the worker.
• Remote changes (db-sync apply-remote, rtc remote update, snapshot import) set :local-tx? false and :gen-undo-ops? false.

Undo/redo recording

• Undo history is recorded only when tx-meta has :local-tx? true.
• Additional existing gates remain: :outliner-op is present, :gen-undo-ops? is not false, and :create-today-journal? is not true.
• Redo stack is cleared on any new local undo-recorded op (existing behavior).

Undo/redo execution safety

• Reverse datoms are computed from original tx-data.
• Conflict detection remains in place (moved blocks, deleted parents, children still exist). These are treated as safe failures for best-effort undo.
• If a conflict is detected or reverse-tx is empty, the undo op is dropped and history cleared for that repo to avoid invalid transacts.
• Undo/redo execution uses tx-meta flags :undo?/:redo? and :gen-undo-ops? false to avoid recursive undo generation.

Consequences

• Undo/redo only affects user-originated changes, never server updates.
• In rare cases, undo may be skipped after a remote conflict, but the database remains valid.
• The model stays simple: no remote history tracking or per-entity versioning.

Plan

1. Confirm the origin flag path

   • Verify all local transact entry points set :local-tx? true (e.g., frontend.db.transact/transact, apply-outliner-ops).
   • Verify all remote/apply/rebase/import paths set :local-tx? false and :gen-undo-ops? false (db-sync apply-remote, rtc remote updates, snapshot import, db restore).

2. Gate undo generation on :local-tx?

   • Update frontend.undo-redo/gen-undo-ops! to require :local-tx? true in tx-meta in addition to existing checks.

3. Enforce best-effort safety

   • On conflict (moved block, deleted parent, remaining children) or on missing reverse tx data, drop the undo op and clear history for repo.

4. Documentation

   • Update relevant internal docs or comments near undo/redo about the origin flag and best-effort semantics.

Test Scenarios (Manual)

1. Local change only

   • Create a block, undo, redo.
   • Expected: undo/redo works and affects only local changes.

2. Remote change only

   • Receive a server update that modifies a block.
   • Expected: undo stack is unchanged; undo does not revert remote update.

3. Local change after remote update

   • Remote updates a block; user edits same block; undo.
   • Expected: undo reverts only the user's edit; remote update remains.

4. Remote delete of parent before undo

   • User creates child; remote deletes parent; user tries undo.
   • Expected: undo is skipped safely; history cleared; no invalid data.

5. Remote move before undo

   • User moves block; remote moves or deletes target; user tries undo.
   • Expected: undo is skipped safely; history cleared; no invalid data.

6. Mixed local ops and remote tx batch

   • Interleave local edits and remote sync.
   • Expected: only local edits appear in undo stack; undo never produces invalid data.

Open Questions

• Do we need a user-visible notification when undo is skipped due to conflicts, or is silent failure acceptable? Silent failure acceptable.