Dasemu
40631362b3
Establishes version control for the personal Logseq DB fork before starting the server-client architecture migration and domain features described in docs/agent-guide and the approved implementation plan. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# ADR 0008: Strengthen DB-Sync Simulation and Replay Coverage
|
|
|
|
Date: 2026-03-17
|
|
Status: Accepted
|
|
|
|
## Context
|
|
Recent DB-sync bugs have repeatedly escaped existing unit and simulation tests.
|
|
The failures were only exposed by real user sessions and browser logs, usually
|
|
after long offline editing, undo/redo, delete/recreate, recycle, and
|
|
sequential reconnect flows.
|
|
|
|
The current test suite has good focused coverage for many individual sync
|
|
helpers, but it still misses several classes of real-world behavior:
|
|
- editor-style multi-step writes such as `insert empty block -> save title`
|
|
- long-lived pending local tx queues
|
|
- undo/redo stacks that survive many sync rounds
|
|
- sequential reconnect flows where one client uploads first and another
|
|
reconnects later
|
|
- replay of real bad `local-txs` and `remote-txs` captured from logs
|
|
|
|
That gap makes DB-sync regressions too dependent on manual reproduction and
|
|
post-hoc log analysis.
|
|
|
|
## Decision
|
|
1. Treat DB-sync simulation as a first-class regression surface, not just a
|
|
long-running smoke test.
|
|
2. Keep adding deterministic repro tests for every real sync bug that reaches
|
|
logs or manual QA.
|
|
3. Expand offline multi-client sims to cover:
|
|
- both reconnect orders
|
|
- repeated offline/online cycles
|
|
- long undo/redo stacks
|
|
- heavier weighting for `delete-blocks`, `move-blocks`,
|
|
`cut-paste-block-with-child`, `undo`, and `redo`
|
|
4. Add invariant checks during simulation, not only after final convergence:
|
|
- no malformed pending tx items
|
|
- no malformed reversed tx items
|
|
- no invalid lookup-only reverse txs
|
|
- no DB structural issues such as missing parent/page or page mismatch
|
|
5. Introduce replay-oriented tests that can execute compact fixtures extracted
|
|
from real logs:
|
|
- persisted `local-txs`
|
|
- remote tx batches
|
|
- reconnect order
|
|
6. Prefer editor-faithful simulation helpers over simplified synthetic ops for
|
|
block creation and editing.
|
|
7. Keep a small corpus of fixed seeds and exact repro flows in the repository,
|
|
so future regressions are rerun automatically in CI and local test runs.
|
|
|
|
## Consequences
|
|
- Positive:
|
|
- Real sync bugs can be captured once and kept as permanent regressions.
|
|
- Multi-client offline behavior gets closer to real user workflows.
|
|
- Broken pending/reverse tx shapes fail earlier and closer to the source.
|
|
- Investigation time drops because logs can be turned into executable tests.
|
|
- Negative:
|
|
- Long-running DB-sync tests become more expensive.
|
|
- Some simulations may still approximate, rather than exactly match, UI
|
|
timing and browser worker behavior.
|
|
- The test suite will need ongoing curation so fixed seeds and replay
|
|
fixtures stay useful instead of becoming noisy.
|
|
|
|
## Verification
|
|
- Exact repro simulation coverage:
|
|
- `bb dev:test -v frontend.worker.db-sync-sim-test/two-clients-offline-delete-vs-children-undo-redo-repro-test`
|
|
- Aggressive offline random coverage:
|
|
- `bb dev:test -v frontend.worker.db-sync-sim-test/two-clients-both-offline-random-undo-redo-sequential-reconnect-sim-test`
|
|
- Reverse/pending tx shape coverage:
|
|
- `bb dev:test -v frontend.worker.db-sync-test/reverse-local-txs-skips-invalid-reverse-step-test`
|
|
- `bb dev:test -v frontend.worker.db-sync-test/reverse-local-txs-skips-missing-lookup-entity-step-test`
|
|
- `bb dev:test -v frontend.worker.db-sync-test/replace-string-block-tempids-rewrites-retract-entity-string-uuid-test`
|
|
- Undo/redo validity coverage:
|
|
- `bb dev:test -v frontend.undo-redo-test/undo-validation-rejects-invalid-recycle-restore-tx-test`
|