logseq/docs/agent-guide/db-sync/db-sync-guide.md

DB-Sync Feature Agent Guide

Purpose

This guide helps AI agents implement and review db-sync features consistently across the client and the Cloudflare Worker. Keep changes scoped, follow the existing flow, and document any protocol or storage changes. Keep this document accurate (file names, paths, commands, and parameters).

Key Code Locations

• Client config: src/main/frontend/config.cljs
• Client runtime: src/main/frontend/worker/db_sync.cljs
• Worker thread API: src/main/frontend/worker/db_worker.cljs
• Handler entry points: src/main/frontend/handler/db_based/db_sync.cljs
• Server worker code: deps/db-sync/src/logseq/db_sync/

Implementation Workflow

1. Define behavior: state the new capability, expected inputs/outputs, and compatibility requirements.
2. Update protocol first (if needed): change protocol.cljs and adjust server/client serialization in tandem.
3. Server changes: update worker.cljs, worker_core.cljs, storage.cljs, or cycle.cljs.
4. Client changes: update db_sync.cljs and thread APIs in db_worker.cljs.
5. Handler glue: add or adjust the entry points in handler/db_based/db_sync.cljs.
6. Function ordering: keep related ClojureScript fns together and ordered to minimize declare usage.

Data, Keywords, and Schema

• Use existing :db-sync/* keywords; add new keywords via logseq.common.defkeywords/defkeyword.
• When adding persisted fields, ensure any migration or index logic is updated on both client and worker.

Fail-Fast Error Policy

• db-sync core code must fail fast on bugs: log an error (log/error) and throw immediately.
• Treat these as bugs (internal invariants or bad server responses on the client):
  • db connection missing when required (client or worker).
  • WS/HTTP response fields missing (e.g., :t, :txs, :reason, :data).
  • Response parse/coercion failures (e.g., transit decode, malli coercion).
  • Unexpected WS/HTTP message type or reason value on the client.
  • Asset operations missing required fields when processing client-side metadata.
  • Invariant violations in tx apply (e.g., tx-data empty after normalization).
• Server-side validation of client input should not throw. Respond with tx/reject or 400 errors for:
  • tx payload type mismatch (e.g., :txs not a sequence of strings).
  • Invalid graph identity (missing/empty graph id or uuid in sync path).
  • Invalid or negative t/t_before values.
• Do not silently recover or drop messages for bug cases; surface them via exceptions.

HTTP API (Bootstrap + Assets)

• HTTP endpoints backfill initial graph data, snapshots, and assets.
• See docs/agent-guide/db-sync/protocol.md for request/response shapes.

Client-Server Message Protocol (WebSocket)

• See docs/agent-guide/db-sync/protocol.md for request/response shapes.

Testing & Verification

• Local dev(client+server): bb dev:db-sync-start runs the db-sync watcher, wrangler dev, and yarn watch with ENABLE_DB_SYNC_LOCAL=true
• DB-sync server side unit-tests: bb dev:db-sync-test

Review Checklist

• Protocol versioning and error handling are consistent across client/server.
• No breaking changes without fallback or migration.
• New data fields are indexed or stored intentionally.
• Logs and errors use :db-sync/* context keys.