logseq/docs/adr/0010-op-driven-client-rebase.md

# ADR 0010: Canonical Op-Driven Client Rebase With Legacy Tx Surgery Isolation

Date: 2026-03-19
Status: Accepted

## Context
Client sync rebase currently relies on custom tx-data surgery to keep pending
local changes alive after remote txs are applied.

That approach has several problems:
- the logic is hard to reason about because it edits datoms instead of replaying
  user intent
- it does not preserve intent well when a local change originated from a higher
  level outliner action
- the helper set keeps growing with special cases for missing refs, structural
  conflicts, and deleted entities
- the outliner-op surface is too large to replay directly without first
  reducing it

At the same time, not every outliner op needs to remain a first-class replay
operation.
Many ops can be safely represented by `:transact` when their tx-data is already
self-contained and does not depend on rerunning outliner logic.

We also have existing persisted pending rows that only store tx-data and reverse
tx-data.
Those rows still need a compatibility path, but that path should not define the
new rebase architecture.

## Decision
1. New pending local tx rows will persist semantic `:outliner-ops` in addition
   to their existing tx-data payload.
2. Client rebase will become op-driven for all new pending rows:
   - reverse local txs
   - apply remote txs
   - transform or drop stored local ops against the post-remote temp db
   - replay the surviving ops to regenerate rebased tx-data
3. Reduce the replay-visible outliner-op surface to a small canonical set:
   - `:insert-blocks`
   - `:save-block`
   - `:move-blocks`
   - `:delete-blocks`
   - `:transact`
4. Normalize higher-level ops into that canonical set before persistence.
   Examples:
   - `:indent-outdent-blocks` becomes `:move-blocks`
   - `:move-blocks-up-down` becomes `:move-blocks`
   - `:rename-page` becomes `:save-block`
5. Introduce an explicit safe-`:transact` classifier:
   - if replaying tx-data directly is sufficient and does not require rerunning
     outliner logic, persist the op as canonical `:transact`
   - otherwise keep it as one of the canonical outliner replay ops
   - expected canonical `:transact` cases include direct tx replay actions such
     as undo, redo, import replay, reaction toggles, and property-value updates
6. Treat undo/redo as canonical `:transact` actions.
   - persist the exact tx-data that the successful undo or redo applied
   - keep the action atomic as one pending tx row
   - do not reconstruct the original higher-level outliner ops that were
     undone or redone
7. Treat `:batch-import-edn` as canonical `:transact` after successful local
   execution.
   - persist the exact tx-data that the import applied
   - do not rerun import expansion during rebase
8. Keep the following op kinds as replay-visible semantic ops because they must
   be reevaluated against current DB state:
   - `:save-block`
   - `:insert-blocks`
   - `:move-blocks`
   - `:delete-blocks`
   - `:create-page`
   - `:delete-page`
   - `:upsert-property`
9. Stop using raw tx-data surgery in the normal rebase path for new rows.
10. Move the current tx-data surgery helpers into a dedicated legacy namespace.
   That legacy namespace is only for compatibility handling of old persisted
   pending rows that do not have stored `:outliner-ops`.
11. Add explicit owned-block filtering in the new op-driven rebase path.
   Initially cover:
   - reaction blocks owned by `:logseq.property.reaction/target`
   - property history blocks owned by `:logseq.property.history/block`
   - property history blocks whose effective owner disappears through deleted
     `:logseq.property.history/ref-value`
12. If a local op creates or updates one of those owned blocks and the owning
   block was deleted remotely, drop that op.
13. Treat each pending tx row as one user action and keep it atomic during
    rebase.
14. If any op in a pending tx becomes invalid during rebase, drop the whole
    pending tx rather than keeping a partial replay of that user action.
15. Keep this refactor client-only for now.
    The sync wire format and server tx log remain unchanged.

## Consequences
- Positive:
  - Rebase reasons about user intent instead of datom accidents.
  - The number of op kinds that rebase must understand becomes much smaller.
  - Safe direct tx replay remains available through canonical `:transact`
    without forcing every operation through outliner code.
  - Undo/redo stays aligned with its real intent: replay the exact applied tx,
    not rerun a reconstructed higher-level command.
  - Import replay stays aligned with its real intent: preserve the exact local
    import result rather than recomputing import expansion later.
  - Legacy compatibility is isolated instead of contaminating the new design.
  - Owned-block cleanup becomes an explicit semantic rule rather than another
    tx-data patch.
  - Rebase behavior stays aligned with the mental model that one pending tx is
    one user action that either survives or is discarded as a whole.
- Negative:
  - We must maintain a canonicalization layer from original outliner ops to the
    reduced replay set.
  - Some existing ops need careful classification to decide whether they are
    safe `:transact` or must stay true outliner replays.
  - For a transition period, the codebase will contain both the new rebase path
    and the isolated legacy compatibility path.
  - If one invalid op is grouped together with otherwise valid work in the same
    pending tx, the whole user action will be lost during rebase.

## Follow-up Constraints
- New pending tx producers must persist canonical `:outliner-ops`.
- New pending tx producers must preserve user-action boundaries because rebase
  will treat each persisted tx row atomically.
- Canonicalization should happen when persisting local pending txs, not lazily
  during rebase.
- Undo/redo producers should persist canonical `:transact` actions using the
  exact tx-data they applied.
- Import producers should persist canonical `:transact` actions using the exact
  tx-data they applied.
- The main sync apply namespace should not call legacy tx-surgery helpers for
  new pending rows.
- The legacy namespace should be clearly named and easy to delete once old
  pending-row compatibility is no longer needed.

## Verification
- Add or update frontend worker db-sync coverage for:
  - persistence of canonical `:outliner-ops`
  - canonical reduction of `:indent-outdent-blocks` and
    `:move-blocks-up-down` into `:move-blocks`
  - safe `:transact` replay versus true outliner replay classification
  - undo/redo persistence as atomic canonical `:transact` actions
  - `:batch-import-edn` persistence as atomic canonical `:transact`
  - `:rename-page` canonicalization to `:save-block`
  - op-driven rebase preserving pending tx boundaries
  - dropping owned reaction/history ops when their owner was deleted remotely
  - dropping the whole pending tx when any op in that user action becomes
    invalid
  - routing legacy pending rows without stored ops through the legacy namespace
- Expected targeted command:
  - `bb dev:test -v frontend.worker.db-sync-test`