cry-synced-db-client 0.1.190 → 0.1.191

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Versions
 
+## 0.1.191 (2026-05-22)
+
+Adopts the cry-db 2.5.0 sync contract. **Requires cry-db ≥ 2.5.0 on the
+server.** Three changes:
+
+### 1. Diff machinery consolidated into cry-db (`computeObjDiff` / `applyObjDiff`)
+
+The local `computeDiff` (in `src/utils/computeDiff.ts`) and
+`SyncedDb.applyDiffLocally` (+ `materializeBracketPath`, `safeDeepClone`)
+were removed. `save()` and init-time dirty overlay now call cry-db's
+`computeObjDiff` / `applyObjDiff` — the server-symmetric counterparts that
+cry-db extracted verbatim from this client. The low-level path primitives
+(`setByPath` / `deleteByPath` / `tokenizePath` / `deepEquals`) are likewise
+imported from cry-db; the local duplicates are gone.
+
+`src/utils/computeDiff.ts` now holds only the client-only dirty-accumulation
+helpers with no server counterpart: `mergeDirtyPath`, `mergeDirtyChanges`,
+`pathsOverlap`.
+
+Imports use the deep path `cry-db/dist/utils.mjs` (pure, zero imports), NOT
+the package root — the root re-exports `Mongo` (mongodb driver) which esbuild
+would drag into the browser bundle. Verified: bundle stays clean (no
+mongodb/bcrypt; 372 KB).
+
+### 2. Sync upload sends `_rev` per entry
+
+Every `updates[]` entry in `updateCollections` now carries `_rev` (the dirty
+entry's `baseRev`; `0` when never synced) at entry level — never inside
+`update`. The server uses it to detect concurrent external writes.
+`CollectionUpdateRequest` is re-exported from `Types.CollectionUpdateRequest`
+(cry-db) so the wire shape stays in lockstep.
+
+### 3. `mustRefresh` adoption with dirty reconciliation
+
+When the server resolves a placeholder (`SEQ_*` / `__hashed__*`) or detects a
+conflict, it returns the full sanitized record in `results.mustRefresh`. The
+new `SyncEngine.adoptMustRefresh` (used by both `uploadDirtyItems` and
+`uploadDirtyItemsForCollection`) honors the cry-db contract — *replace the
+local record with the `mustRefresh` entry, then run the dirty-merge; apply
+`mustRefresh` BEFORE the merge so unsynced local edits to other fields are
+reconciled rather than clobbered*:
+
+1. Captures the dirty entry + upload snapshot BEFORE the success-clear.
+2. Takes the `mustRefresh` record as the base.
+3. Re-applies (via `applyObjDiff`) only dirty paths NOT in the upload snapshot
+   — local edits made during the round-trip. Uploaded paths (incl. a resolved
+   placeholder) are owned by the server record and are not re-applied.
+4. Writes the merged row to Dexie + in-mem (`_deleted`/`_archived` → local
+   delete). The advanced `_rev` makes conflict resolution accept the write.
+5. Keeps the re-applied paths dirty (rebased on the new `_rev`) so they upload
+   next sync.
+
+In the common case (no mid-flight edits) the record is adopted verbatim.
+
+### Tests / docs
+
+- New `test/uploadRevAndMustRefresh.test.ts` (4 cases): `_rev: 0` on fresh
+  insert + not inside `update`; `_rev = baseRev` after a synced edit;
+  `mustRefresh` adoption (resolved placeholder); round-trip-edit
+  reconciliation.
+- Diff unit tests repointed to cry-db (`computeObjDiff` / `applyObjDiff`),
+  kept as a guard. Removed the dead `hasDotNotationPaths` (no callers).
+- Mocks return `mustRefresh: []`; new `MockRestInterfaceFake` test helpers
+  (`setUpdateCollectionsForcedMustRefresh`, `lastUpdateCollectionsRequest`).
+- CLAUDE.md / SPEC.md + comments updated.
+
 ## 0.1.190 (2026-05-15)
 
 ### `addCollectionsToSync(specs[])` — batch register with single-RTT download