logseq/docs/adr/0012-worker-owned-undo-redo.md

ADR 0012: Move Undo/Redo Recording and Replay to the DB Worker

Date: 2026-03-21 Status: Proposed

Context

frontend.undo-redo currently runs on the main thread.

That means undo and redo recording depends on main-thread listeners observing DB tx reports after they have already crossed the worker boundary.

This split has become a recurring source of drift:

• the worker is the source of truth for the browser Datascript DB
• the worker already persists local actions in client-op storage
• the worker already owns rebase and semantic replay
• the main thread still owns undo/redo stack mutation for DB history

That architecture forces the main thread to reconstruct DB history from a worker-synchronized tx report instead of observing the DB change at the place where it actually happens.

The result is fragile metadata flow.

We have already seen bugs caused by:

• :outliner-ops being stripped or reshaped during worker-to-main-thread sync
• undo/redo-generated tx rows overwriting the original client-op row
• semantic forward and inverse ops diverging between worker persistence and main-thread undo stack payloads
• special cases such as :replace-empty-target?, block concat, and :set-block-property depending on worker-local replay behavior anyway

The one main-thread-only input that frontend.undo-redo still needs is @state/*editor-info.

Today that atom is read and reset on the main thread inside frontend.undo-redo/gen-undo-ops!.

If undo/redo recording moves to the worker, the worker can no longer deref the main-thread atom directly.

Decision

1. DB undo/redo recording and replay move to the DB worker.
2. The worker becomes the only place that listens to DB tx reports for DB history generation.
3. The main thread remains responsible for UI-derived history inputs only: editor cursor/focus metadata and UI-state snapshots.
4. @state/*editor-info will not be read from the worker directly. It will be replaced by an explicit main-thread-to-worker handoff protocol.
5. The worker owns the undo stack and redo stack for DB actions and UI-adjacent metadata attached to those actions.
6. The main thread will invoke worker APIs for:
   • recording pending editor info
   • recording UI-only state history entries
   • undo
   • redo
   • clear history
7. The main thread will stop generating DB undo history from :db/sync-changes events.
8. The worker-owned history row should not keep a separate persisted :db-sync/outliner-ops field. :db-sync/forward-outliner-ops is the only canonical persisted forward semantic field.

Rationale

The worker is already the place where all browser DB facts become real:

• local outliner ops are applied there
• remote sync txs are applied there
• pending local rows are persisted there
• semantic forward and inverse ops are canonicalized there
• rebase happens there

Undo/redo recording should therefore observe worker DB tx reports directly instead of reconstructing them after the worker has serialized, sanitized, and rebroadcast them.

That removes an entire class of metadata transport bugs.

It also matches ADR 0011 more closely: the worker action row is supposed to be the source of truth for DB history. Recording DB history on the main thread is in tension with that decision.

Target Architecture

+------------------------------+          thread-api            +---------------------------+
| Main thread                  | ----------------------------> | DB worker                  |
|                              |                               |                           |
| editor lifecycle             |  push pending editor-info     | pending editor-info store |
| route/sidebar state          |  push ui-state entries        | undo stack                |
| history handler              |  undo / redo / clear          | redo stack                |
| restore cursor + route       | <---------------------------- | DB replay + result meta   |
+------------------------------+                               +---------------------------+

The worker stack entry becomes the single logical history item for both:

• DB replay metadata
• UI-adjacent metadata needed after replay

Representative worker stack item:

{:tx-id #uuid "..."
 :kind :db-action ; or :ui-state-only
 :editor-info {:block-uuid ...
               :container-id ...
               :start-pos ...
               :end-pos ...}
 :ui-state-str "...optional transit..."
 :forward-outliner-ops [...]
 :inverse-outliner-ops [...]
 :outliner-op :save-block}

The target row schema is therefore:

• :db-sync/tx-id
• :db-sync/outliner-op
• :db-sync/forward-outliner-ops
• :db-sync/inverse-outliner-ops
• worker-owned cursor/UI metadata as needed

It intentionally does not include a separate persisted :db-sync/outliner-ops.

*editor-info Handoff

The worker must not read @state/*editor-info directly.

That atom lives on the main thread and represents ephemeral UI state.

Instead, we will replace the implicit shared-state read with an explicit handoff.

Rule

The main thread owns editor-info production. The worker owns editor-info consumption.

Mechanism

Add a worker-side pending editor-info slot keyed by repo.

Suggested API:

• :thread-api/undo-redo-set-pending-editor-info
  • args: repo, editor-info-or-nil
• :thread-api/undo-redo-record-ui-state
  • args: repo, ui-state-str
• :thread-api/undo-redo-undo
  • args: repo
• :thread-api/undo-redo-redo
  • args: repo
• :thread-api/undo-redo-clear-history
  • args: repo

Consumption and reset semantics

When the worker records a new local DB action into undo history:

1. read pending editor-info for the repo
2. attach it to the new stack item if present
3. clear the pending editor-info slot immediately after the stack item is created

This preserves the current one-shot semantics of @state/*editor-info without requiring the worker to deref or mutate main-thread state directly.

Main-thread responsibilities

The main thread should:

• capture editor-info at the same points it does today
• send the current snapshot to the worker before the local DB action is submitted or immediately when editor focus/cursor changes, whichever path is simpler and consistent
• stop relying on worker :db/sync-changes to retroactively capture cursor state

The main thread may still keep a local *editor-info atom for editor UI code, but it is no longer the undo recorder’s source of truth.

UI-State History

UI-state-only undo entries such as route/sidebar snapshots cannot be generated by the worker from DB tx reports.

Those entries should be pushed explicitly from the main thread into the worker history stack.

Two entry classes will therefore exist in the worker stack:

1. :db-action
2. :ui-state-only

Undo/redo execution will return enough metadata for the main thread to restore:

• route
• sidebar state
• editor cursor

The worker should not attempt to perform UI restoration itself.

Consequences

Positive

• DB undo/redo history is recorded at the actual DB source of truth.
• No more dependence on :db/sync-changes preserving semantic metadata exactly.
• Worker persistence, worker replay, and worker history all use the same action identity.
• Main-thread history bugs caused by tx-meta sanitization disappear.
• Undo/redo debugging becomes simpler because the worker owns the full DB history lifecycle.

Negative

• The worker history stack now stores UI-adjacent metadata that originates on the main thread.
• New thread APIs are required.
• Main-thread editor lifecycle code must actively synchronize pending editor-info.
• The migration touches both undo/redo and worker message flow at once.

Implementation Plan

Phase 1. Introduce worker-owned undo/redo module

• Create a worker namespace, e.g. /Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/worker/undo_redo.cljs
• Move stack storage and DB history generation there.
• Register worker DB listener(s) against the worker Datascript conn.
• Remove persisted :db-sync/outliner-ops from the target worker history row shape instead of carrying it forward as a parallel field.

Phase 2. Replace main-thread DB history generation

• Remove DB-history recording from /Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/undo_redo.cljs
• Keep only main-thread coordination helpers if still needed.
• Route history handler calls through worker thread APIs.

Phase 3. Add pending editor-info handoff

• Add worker API to set pending editor-info.
• Update /Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/modules/outliner/ui.cljc and any direct local transact paths to send editor-info to the worker.
• Consume and clear the pending editor-info slot when a local history item is recorded.

Phase 4. Move UI-state history writes to worker

• Replace record-ui-state! main-thread stack mutation with worker API calls.
• Keep route/sidebar serialization on the main thread.

Phase 5. Return worker-owned undo/redo result metadata

• Worker undo/redo APIs should return:
  • :undo?
  • :editor-info
  • :ui-state-str
  • optional block content or replay diagnostics
• Main-thread history handler restores cursor and route from that result.

Files Expected to Change

File	Change
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/undo_redo.cljs	Remove main-thread DB listener ownership, keep only coordinator logic if still needed.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/handler/history.cljs	Call worker undo/redo APIs and restore UI from returned metadata.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/modules/outliner/ui.cljc	Send editor-info snapshots to the worker before local action submission.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/handler/editor/lifecycle.cljs	Stop recording editor-info directly into main-thread undo stack; feed worker pending editor-info instead.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/worker/db_worker.cljs	Expose worker thread APIs for pending editor-info, UI-state history, undo, redo, and clear-history.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/worker/db_listener.cljs	Attach worker undo/redo recording directly to worker DB tx reports.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/worker/sync/client_op.cljs	Remove :db-sync/outliner-ops from the target worker-owned undo/redo row model and use :db-sync/forward-outliner-ops instead.
/Users/tiensonqin/Codes/projects/logseq/web/src/main/frontend/worker/sync/apply_txs.cljs	Keep worker replay aligned with worker-owned history rows.
/Users/tiensonqin/Codes/projects/logseq/web/src/test/frontend/undo_redo_test.cljs	Replace main-thread DB-history expectations with coordinator/result expectations.
/Users/tiensonqin/Codes/projects/logseq/web/src/test/frontend/worker/db_sync_test.cljs	Add worker-owned history recording and replay coverage.

Alternatives Considered

1. Keep frontend.undo-redo on the main thread and preserve more tx-meta

Rejected.

This keeps the wrong ownership boundary. It reduces one transport bug at a time but does not remove the architectural duplication between main-thread history and worker DB history.

2. Let the worker call back into the main thread to read @state/*editor-info

Rejected.

That would create an implicit cross-thread read dependency around ephemeral UI state. It is harder to reason about than explicit handoff, and reset semantics become ambiguous.

3. Keep DB history in the worker and UI history in a separate main-thread stack

Possible, but inferior to a single worker-owned stack item keyed by tx-id.

It still splits one logical action across two structures and reintroduces alignment problems.

Open Questions

1. Should pending editor-info be pushed:
   • only at transact boundaries
   • or eagerly on every cursor change with last-write-wins semantics?

Recommendation: push at transact boundaries first. It matches current one-shot behavior and avoids unnecessary worker chatter.

2. Should :ui-state-only entries live in the same stack as DB actions?

Recommendation: yes. One logical undo/redo stream is simpler than coordinating two stacks.

3. Do we still need @state/*editor-info after the migration?

Recommendation: keep it as a UI helper until the move is complete, but stop using it as undo history source of truth.