doc(db-sync): sync db-sync docs and codebase again

deps/db-sync/worker/README.md

@@ -1,55 +0,0 @@
-## Cloudflare Sync Worker (Skeleton)
-
-This worker provides a simple WebSocket-based sync protocol backed by a
-Durable Object using SQLite storage and the Logseq datascript fork.
-
-### Bindings
-
-- `LOGSEQ_SYNC_DO`: Durable Object namespace
-- `LOGSEQ_SYNC_INDEX_DO`: Durable Object namespace for graph registry
-
-### Routes
-
-- `GET /health`
-  - Returns a JSON health response
-- `GET /graphs`
-  - Returns the list of registered graphs
-- `POST /graphs`
-  - Registers or updates a graph
-- `DELETE /graphs/:graph-id`
-  - Deletes a graph and resets its DO state
-- `GET /sync/:graph-id`
-  - Proxies to the Durable Object for the given graph
-
-### WebSocket Protocol
-
-Messages are JSON. The payloads for `tx` and `snapshot` use Transit strings to
-preserve keywords and UUIDs.
-
-Client -> Server:
-
-- `{ "type": "hello", "client": "...", "since": 0 }`
-- `{ "type": "tx", "client": "...", "t_before": 0, "tx": "<transit>" }`
-- `{ "type": "pull", "since": 0 }`
-- `{ "type": "ping" }`
-<!-- - `{ "type": "snapshot" }` -->
-
-
-Server -> Client:
-
-- `{ "type": "hello", "t": 1 }`
-- `{ "type": "tx/batch/ok", "t": 2 }`
-- `{ "type": "tx/reject", "reason": "cycle", "server_values": "<transit>" }`
-- `{ "type": "pull/ok", "t": 2, "txs": [{"t": 1, "tx": "<transit>"}] }`
-- `{ "type": "snapshot/ok", "t": 2, "datoms": "<transit>" }`
-- `{ "type": "pong" }`
-
-### Notes
-
-- The sync protocol is intentionally minimal for testing.
-- For local testing, run `wrangler dev` and use `deps/db-sync/worker/scripts/dev_test.sh`.
-- For WebSocket testing, run `node deps/db-sync/worker/scripts/ws_test.js`.
-- If you switch schema versions, clear local DO state.
-- Build the worker bundle with `clojure -M:cljs release db-sync`.
-- For dev, run `clojure -M:cljs watch db-sync` in one terminal and
-  `wrangler dev` in another.

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

@@ -9,7 +9,6 @@ This guide helps AI agents implement and review db-sync features consistently ac
 - 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/`
-- Worker build/test notes: `deps/db-sync/worker/README.md`
 
 ## Implementation Workflow
 1) **Define behavior**: state the new capability, expected inputs/outputs, and compatibility requirements.
@@ -22,29 +21,13 @@ This guide helps AI agents implement and review db-sync features consistently ac
 - 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.
 
-## Client-Server Message Protocol (WebSocket)
-- Transport: WebSocket `ws(s)` to `/sync/:graph-id` (client builds URL from config and appends `?token=...` when available).
-- Encoding: JSON objects; `tx` payloads are Transit strings.
-- Client -> Server:
-  - `{"type":"hello","client":"<repo-id>"}`: initial hello; server responds with `t`.
-  - `{"type":"pull","since":<t>}`: request txs after `since` (defaults to 0).
-  - `{"type":"tx/batch","t_before":<t>,"txs":["<tx-transit>", ...]}`: upload batch.
-  - `{"type":"ping"}`: optional keepalive; server replies `pong`.
-- Server -> Client:
-  - `{"type":"hello","t":<t>}`: server hello with current t.
-  - `{"type":"pull/ok","t":<t>,"txs":[{"t":<t>,"tx":"<tx-transit>"}...]}`: pull response.
-  - `{"type":"tx/batch/ok","t":<t>}`: batch accepted.
-  - `{"type":"changed","t":<t>}`: broadcast that server state advanced; client should `pull`.
-  - `{"type":"tx/reject","reason":"stale","t":<t>}`: client tx based on stale t.
-  - `{"type":"tx/reject","reason":"cycle","data":"<transit {:attr <kw> :server_values ...}>"}`: cycle detected with server values.
-  - `{"type":"tx/reject","reason":"empty tx data"|"invalid tx"}`: invalid batch.
-  - `{"type":"pong"}`: keepalive response.
-  - `{"type":"error","message":"..."}`: invalid/unknown message.
-
 ## 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`
 - Unit tests: `bb dev:lint-and-test`

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

@@ -58,11 +58,13 @@
 - `POST /sync/:graph-id/tx/batch`
   - Same as WS tx/batch. Body: `{"t_before":<t>,"txs":["<tx-transit>", ...]}`.
   - Response: `{"type":"tx/batch/ok","t":<t>}` or `{"type":"tx/reject","reason":...}`.
+  - Error response (400): `{"error":"missing body"|"invalid tx"}`.
 - `GET /sync/:graph-id/snapshot/rows?after=<addr>&limit=<n>`
-  - Pull sqlite kvs rows. Response: `{"rows":[[addr,content,addresses]...],"last_addr":<addr>,"done":true|false}`.
+  - Pull sqlite kvs rows. Response: `{"rows":[{"addr":<addr>,"content":"<transit>","addresses":<json|null>}...],"last_addr":<addr>,"done":true|false}`.
 - `POST /sync/:graph-id/snapshot/import`
   - Import sqlite kvs rows. Body: `{"reset":true|false,"rows":[[addr,content,addresses]...]}`.
   - Response: `{"ok":true,"count":<n>}`.
+  - Error response (400): `{"error":"missing body"|"invalid body"}`.
 - `DELETE /sync/:graph-id/admin/reset`
   - Drop/recreate per-graph tables. Response: `{"ok":true}`.