cry-synced-db-client 0.1.155 → 0.1.157

package/CHANGELOG.md

@@ -1,49 +1,137 @@
 # Versions
 
-## 0.1.154
+## 0.1.156
 
-### `evictOnWake` config
+Three related fixes targeting **dirty-payload metadata leak** and
+**concurrent array merge corruption** observed in production
+(tenant *prvak*, obravnave with stale offline edits silently dropping
+field updates from a second device).
 
-New optional field on `SyncedDbConfig`. When set to `true`, scope-exit
-eviction runs on every wake event (`sync()` whose `calledFrom` starts
-with `'wake-sync:'`), bypassing the `evictStaleRecordsEveryHrs` interval
-gate. The eviction is bundled into the wake sync's `findNewerManyStream`
-call — single RTT, same shape as existing 8h auto-eviction.
+### Bracket-by-_id array path notation in `computeDiff`
 
-Use with `scopeExitLookbehindMs` to ensure scope-exit detection covers
-records mutated within the lookbehind window. Together they guarantee
-cross-device close-outs become visible on the very next wake instead of
-waiting up to `evictStaleRecordsEveryHrs`.
+Array element paths emitted by `computeDiff` now use bracket notation
+keyed by the element's `_id`:
 
-`evictStaleRecordsEveryHrs` continues to gate non-wake syncs (interval
-auto-sync ticks, manual `sync()` calls without `'wake-sync:*'` prefix).
+```diff
+- "koraki.0.diagnostika"     // position-based — corrupts on reorder
++ "koraki[<korakId>].diagnostika"  // identity-based — survives reorder
+```
+
+Why: with position-based dot notation, if device B reordered or
+inserted/removed earlier elements while device A was offline, A's
+upload of `koraki.0.field` would mongo `$set` the wrong element on
+the server.
+
+`tokenizePath()` is now exported and accepts both `.` and `[…]`
+delimiters. `setByPath` and `isDescendantOrEqual` updated to handle
+bracket segments.
+
+### `translateBracketPathsToIndex` (upload-time)
+
+`SyncEngine.uploadDirtyItems` translates bracket paths to mongo
+`$set`-compatible index paths just before upload, using the current
+local entity (post-sync, post-merge) as the source of truth for
+`_id → index` mapping. Paths whose `_id` cannot be resolved (concurrent
+deletion on the server) are dropped — preferring partial loss over
+silently writing to the wrong index.
+
+### Server-managed metadata excluded from dirty payloads
+
+`computeDiff` skips `_ts`, `_rev`, `_csq` at the top level. As a
+defense-in-depth, `SyncEngine.uploadDirtyItems` strips any path
+beginning with `_ts.`, `_rev.`, `_csq.` before upload (mitigates legacy
+dirty rows written by older library versions).
+
+Why: the BSON `Timestamp` shape `{t, i}` was being recursed into by
+`computeDiff`, emitting paths like `_ts.t` / `_ts.i`. These conflicted
+with mongo's `$currentDate` operator on the server — silent rejection
+left items dirty forever and blocked subsequent uploads.
+
+### `mergeObjectArrays` — server composition is authoritative
+
+When parent `_rev` says the server is newer (`parentServerWins=true`):
+
+1. **Drop local-only elements**. Per directive: *"če ima server višji
+   `_rev` in nima več elementa z nekim `_id`, client ne sme zopet
+   dodati tega zapisa v array"*. The server has authoritatively
+   removed the element; the client must not resurrect it.
+2. **Server's value wins on primitive conflicts inside surviving
+   sub-elements** (Option B — propagate `_rev` for *comparison only*,
+   never written into sub-objects).
+
+When local `_rev >= external _rev`, behavior is unchanged: union
+semantics preserve local-only elements (server is older / equal).
+
+### `mergeObjectArrays` — fail-fast on missing `_id`
+
+Per directive: array elements MUST carry `_id`. If any element on
+either side lacks `_id`, log `console.error` for each offender and
+fall back to **whole-array replace by higher `_rev`** (parent's verdict
+chooses local vs external). Prevents silent merge corruption when
+schemas regress.
+
+### `fixDotnetArrays` (legacy mitigation)
+
+Temporary upload-time scrubber dropping legacy position-based array
+paths (`field.<digit>(.…)?`) when `serverRev > baseRev`. Marked for
+removal after ~2026-05-15 once all clients have re-synced.
 
-Default: `false`.
+## 0.1.155
 
-## 0.1.153
+Two new `SyncedDbConfig` fields targeting **cross-device scope-exit**
+detection: situations where one device modifies a record so it no longer
+matches the positive `syncConfig.query` (e.g. status `'odprta'` →
+`'zaključena'` on a `{status: {$ne: 'zaključena'}}` query) while another
+device is offline at that moment. The filtered delta feed never re-ships
+the post-mutation row, so the second device's local cache otherwise
+goes stale forever.
 
-### `scopeExitLookbehindMs` config
+### `scopeExitLookbehindMs?: number` (default `0`)
 
-New optional field on `SyncedDbConfig`. When set (> 0), server-assisted
-scope-exit detection (auto-eviction bundled with `sync()`, plus the batch
-`evictOutOfScopeRecordsAll` path) uses `_ts > now - scopeExitLookbehindMs`
-instead of `_ts > lastSyncTs` for the `findNewerMany` spec timestamp.
+Default lookbehind window (ms) for server-assisted scope-exit detection
+in auto-eviction (`sync()` bundled) and `evictOutOfScopeRecordsAll`.
+When set (> 0), the scope-exit `findNewerMany` spec uses
+`_ts > now - scopeExitLookbehindMs` instead of `_ts > lastSyncTs`.
 
 Why: with the legacy `lastSyncTs` cursor, the scope-exit query
 `{$nor:[positiveQuery], _id:{$in:chunk}, _ts > lastSyncTs}` excluded any
-record whose server-side `_ts` predates the device's `lastSyncTs`. Typical
-cross-device close-out scenario (device A closes a record while device B
-is offline; B comes back online and syncs many newer records, advancing
-`lastSyncTs` past the close-out's `_ts`) → server returned 0 scope-exit
-candidates forever. Per-call override via
-`evictOutOfScopeRecords({outOfWindowLookbehindMs})` is unchanged and now
-also falls back to `scopeExitLookbehindMs` when no per-call value is given.
-
-Default: `0` (legacy behavior). Recommended for multi-device deployments:
-`3 * 24 * 3600 * 1000` (3 days). Combine with periodic
-`refreshDatabaseFromServer()` (e.g. when `lastInitialSync()` exceeds the
-same threshold) to also cover scope-exit events older than the lookbehind
-window.
+record whose server-side `_ts` predated the device's `lastSyncTs`.
+Typical cross-device close-out scenario: device A closes a record at T0,
+device B (offline at T0) reconnects at T1 and syncs many newer records,
+advancing `lastSyncTs` past T0 → server returned 0 scope-exit candidates
+forever even though the closed record was a clear scope-exit.
+
+Per-call override remains via
+`evictOutOfScopeRecords({outOfWindowLookbehindMs})` — now also falls
+back to global `scopeExitLookbehindMs` when no per-call value is given.
+
+Recommended for multi-device deployments: `3 * 24 * 3600 * 1000` (3 days).
+Combine with periodic `refreshDatabaseFromServer()` (e.g. when
+`lastInitialSync()` exceeds the same threshold) to cover drift older
+than the lookbehind window.
+
+### `evictOnWake?: boolean` (default `false`)
+
+When `true`, scope-exit eviction runs on every wake event (`sync()`
+whose `calledFrom` starts with `'wake-sync:'`), bypassing the
+`evictStaleRecordsEveryHrs` interval gate. The eviction is bundled into
+the wake sync's `findNewerManyStream` call — single RTT, same shape as
+existing 8h auto-eviction (`evictStaleRecordsEveryHrs` continues to gate
+non-wake syncs: interval auto-sync ticks, manual `sync()` calls without
+`'wake-sync:*'` prefix).
+
+Combine with `scopeExitLookbehindMs` to guarantee that any cross-device
+close-out within the lookbehind window becomes visible on the very next
+wake.
+
+### Implementation
+
+- `SyncedDb.ts` `_isAutoEvictionDue(calledFrom?)` — wake-sync trigger
+  bypasses interval gate when `evictOnWake = true`.
+- New private `_scopeExitTimestamp(collection)` — single source of truth
+  for the scope-exit query timestamp; honors `scopeExitLookbehindMs`.
+- `_collectScopeExitPlan` and single-collection `evictOutOfScopeRecords`
+  both route through the new helper.
 
 ## Unreleased
 

package/dist/index.js

@@ -345,10 +345,11 @@ function computeArrayDiff(existingArr, updateArr, basePath, diff) {
     return;
   }
   for (let i = 0; i < updateArr.length; i++) {
+    const elementId = String(updateArr[i]._id);
     computeDiffInto(
       existingArr[i],
       updateArr[i],
-      `${basePath}.${i}`,
+      `${basePath}[${elementId}]`,
       diff
     );
   }
@@ -380,49 +381,106 @@ function computeDiffInto(existing, update, basePath, diff) {
     computeDiffInto(existing[key], update[key], childPath, diff);
   }
 }
+var SERVER_MANAGED_METADATA_KEYS = /* @__PURE__ */ new Set(["_ts", "_rev", "_csq"]);
 function computeDiff(existing, update) {
   const diff = {};
   if (!update || typeof update !== "object") return diff;
   if (existing === null || existing === void 0) {
-    return __spreadValues({}, update);
+    const cleaned = {};
+    for (const k of Object.keys(update)) {
+      if (SERVER_MANAGED_METADATA_KEYS.has(k)) continue;
+      cleaned[k] = update[k];
+    }
+    return cleaned;
   }
   for (const key of Object.keys(update)) {
+    if (SERVER_MANAGED_METADATA_KEYS.has(key)) continue;
     computeDiffInto(existing[key], update[key], key, diff);
   }
   return diff;
 }
 function isDescendantOrEqual(path, candidate) {
   if (path === candidate) return true;
-  return path.startsWith(candidate + ".");
+  if (!path.startsWith(candidate)) return false;
+  const next = path[candidate.length];
+  return next === "." || next === "[";
+}
+function tokenizePath(path) {
+  const out = [];
+  let buf = "";
+  for (let i = 0; i < path.length; i++) {
+    const ch = path[i];
+    if (ch === ".") {
+      if (buf) {
+        out.push(buf);
+        buf = "";
+      }
+    } else if (ch === "[") {
+      if (buf) {
+        out.push(buf);
+        buf = "";
+      }
+      const close = path.indexOf("]", i);
+      if (close < 0) {
+        buf += ch;
+        continue;
+      }
+      out.push(path.substring(i, close + 1));
+      i = close;
+    } else {
+      buf += ch;
+    }
+  }
+  if (buf) out.push(buf);
+  return out;
 }
 function setByPath(target2, path, value) {
   if (target2 === null || target2 === void 0) return false;
-  const parts = path.split(".");
+  const parts = tokenizePath(path);
   let current = target2;
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
-    const idx = /^\d+$/.test(part) ? Number(part) : null;
-    let next;
-    if (Array.isArray(current) && idx !== null) {
-      next = current[idx];
-    } else if (typeof current === "object") {
-      next = current[part];
-    } else {
-      return false;
-    }
-    if (next === null || next === void 0) return false;
+    const next = navigateSegment(current, part);
+    if (next === void 0) return false;
     current = next;
   }
   const last = parts[parts.length - 1];
-  const lastIdx = /^\d+$/.test(last) ? Number(last) : null;
-  if (Array.isArray(current) && lastIdx !== null) {
-    current[lastIdx] = value;
-  } else if (typeof current === "object") {
-    current[last] = value;
-  } else {
-    return false;
+  return setSegment(current, last, value);
+}
+function navigateSegment(current, part) {
+  if (current === null || current === void 0) return void 0;
+  if (part.startsWith("[") && part.endsWith("]")) {
+    const idStr = part.slice(1, -1);
+    if (!Array.isArray(current)) return void 0;
+    return current.find((item) => item && String(item._id) === idStr);
   }
-  return true;
+  if (/^\d+$/.test(part) && Array.isArray(current)) {
+    return current[Number(part)];
+  }
+  if (typeof current === "object") {
+    return current[part];
+  }
+  return void 0;
+}
+function setSegment(current, part, value) {
+  if (current === null || current === void 0) return false;
+  if (part.startsWith("[") && part.endsWith("]")) {
+    const idStr = part.slice(1, -1);
+    if (!Array.isArray(current)) return false;
+    const idx = current.findIndex((item) => item && String(item._id) === idStr);
+    if (idx < 0) return false;
+    current[idx] = value;
+    return true;
+  }
+  if (/^\d+$/.test(part) && Array.isArray(current)) {
+    current[Number(part)] = value;
+    return true;
+  }
+  if (typeof current === "object") {
+    current[part] = value;
+    return true;
+  }
+  return false;
 }
 function mergeDirtyPath(accumulated, newPath, newValue) {
   for (const existingKey of Object.keys(accumulated)) {
@@ -2543,9 +2601,10 @@ function resolveConflict(local, external) {
   }
   return mergeObjects(local, external);
 }
-function mergeObjects(local, external) {
+function mergeObjects(local, external, parentServerWins = false) {
   const result = __spreadValues({}, local);
-  const serverWinsOnConflict = typeof local._rev === "number" && typeof external._rev === "number" && external._rev > local._rev;
+  const ownServerWins = typeof local._rev === "number" && typeof external._rev === "number" && external._rev > local._rev;
+  const serverWinsOnConflict = parentServerWins || ownServerWins;
   for (const key of Object.keys(external)) {
     if (key === "_id" || key === "_dirty") {
       continue;
@@ -2560,16 +2619,16 @@ function mergeObjects(local, external) {
       continue;
     }
     if (Array.isArray(localValue) && Array.isArray(externalValue)) {
-      result[key] = mergeArrays(localValue, externalValue);
+      result[key] = mergeArrays(localValue, externalValue, serverWinsOnConflict);
     } else if (isPlainObject4(localValue) && isPlainObject4(externalValue)) {
-      result[key] = mergeObjects(localValue, externalValue);
+      result[key] = mergeObjects(localValue, externalValue, serverWinsOnConflict);
     } else if (serverWinsOnConflict) {
       result[key] = externalValue;
     }
   }
   return result;
 }
-function mergeArrays(local, external) {
+function mergeArrays(local, external, parentServerWins = false) {
   if (local.length === 0) {
     return external.slice();
   }
@@ -2581,13 +2640,55 @@ function mergeArrays(local, external) {
     return Array.from(set2);
   }
   if (isPlainObject4(firstLocal) || isPlainObject4(firstExternal)) {
-    return mergeObjectArrays(local, external);
+    return mergeObjectArrays(local, external, parentServerWins);
   }
   const set = new Set(local);
   for (const item of external) set.add(item);
   return Array.from(set);
 }
-function mergeObjectArrays(local, external) {
+function mergeObjectArrays(local, external, parentServerWins = false) {
+  const objectItemsMissingId = [];
+  for (const item of local) {
+    if (item && typeof item === "object" && item._id == null) {
+      objectItemsMissingId.push(item);
+    }
+  }
+  for (const item of external) {
+    if (item && typeof item === "object" && item._id == null) {
+      objectItemsMissingId.push(item);
+    }
+  }
+  if (objectItemsMissingId.length > 0) {
+    for (const item of objectItemsMissingId) {
+      console.error(
+        "[mergeObjectArrays] array element without _id \u2014 falling back to whole-array replace by higher _rev:",
+        item
+      );
+    }
+    return parentServerWins ? external.slice() : local.slice();
+  }
+  if (parentServerWins) {
+    const result2 = [];
+    for (const extItem of external) {
+      if (!extItem || typeof extItem !== "object") {
+        result2.push(extItem);
+        continue;
+      }
+      if ("_id" in extItem) {
+        const localIndex = local.findIndex(
+          (l) => l && typeof l === "object" && "_id" in l && String(l._id) === String(extItem._id)
+        );
+        if (localIndex >= 0) {
+          result2.push(mergeObjects(local[localIndex], extItem, parentServerWins));
+        } else {
+          result2.push(extItem);
+        }
+      } else {
+        result2.push(extItem);
+      }
+    }
+    return result2;
+  }
   const result = local.slice();
   const localIds = /* @__PURE__ */ new Map();
   for (let i = 0; i < local.length; i++) {
@@ -2604,7 +2705,7 @@ function mergeObjectArrays(local, external) {
     if ("_id" in extItem) {
       const localIndex = localIds.get(String(extItem._id));
       if (localIndex !== void 0) {
-        result[localIndex] = mergeObjects(result[localIndex], extItem);
+        result[localIndex] = mergeObjects(result[localIndex], extItem, parentServerWins);
       } else {
         result.push(extItem);
       }
@@ -2618,6 +2719,76 @@ function isPlainObject4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date);
 }
 
+// src/utils/fixDotnetArrays.ts
+function hasArrayIndexPath(key) {
+  return /\.\d+(\.|$)/.test(key);
+}
+function fixDotnetArrays(changes, serverRev, baseRev) {
+  const topLevelArrays = /* @__PURE__ */ new Set();
+  for (const [k, v] of Object.entries(changes)) {
+    if (Array.isArray(v)) topLevelArrays.add(k);
+  }
+  const isStale = typeof serverRev === "number" && typeof baseRev === "number" && serverRev > baseRev;
+  const cleaned = {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (hasArrayIndexPath(key)) {
+      const arrayField = key.split(".")[0];
+      if (arrayField && topLevelArrays.has(arrayField)) continue;
+      if (isStale) continue;
+    }
+    cleaned[key] = value;
+  }
+  return cleaned;
+}
+
+// src/utils/translateBracketPaths.ts
+function translateBracketPathsToIndex(changes, entity) {
+  const result = {};
+  for (const [key, value] of Object.entries(changes)) {
+    const translated = translateKey(key, entity);
+    if (translated !== null) {
+      result[translated] = value;
+    }
+  }
+  return result;
+}
+function translateKey(key, entity) {
+  const parts = tokenizePath(key);
+  const out = [];
+  let cursor = entity;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part.startsWith("[") && part.endsWith("]")) {
+      const idStr = part.slice(1, -1);
+      if (!Array.isArray(cursor)) return null;
+      const idx = cursor.findIndex(
+        (item) => item && String(item._id) === idStr
+      );
+      if (idx < 0) return null;
+      out.push(String(idx));
+      cursor = cursor[idx];
+      continue;
+    }
+    out.push(part);
+    if (cursor === null || cursor === void 0) {
+      for (let j = i + 1; j < parts.length; j++) {
+        const p = parts[j];
+        if (p.startsWith("[") && p.endsWith("]")) return null;
+        out.push(p);
+      }
+      return out.join(".");
+    }
+    if (/^\d+$/.test(part) && Array.isArray(cursor)) {
+      cursor = cursor[Number(part)];
+    } else if (typeof cursor === "object") {
+      cursor = cursor[part];
+    } else {
+      cursor = void 0;
+    }
+  }
+  return out.join(".");
+}
+
 // src/db/sync/SyncEngine.ts
 var _SyncEngine = class _SyncEngine {
   constructor(config) {
@@ -2821,6 +2992,7 @@ var _SyncEngine = class _SyncEngine {
         dirtyChangesMap.set(String(dirtyItem._id), dirtyItem);
       }
       const updates = [];
+      const skipped = [];
       const ids = dirtyChanges.map((dc) => dc._id);
       const fullItems = await this.dexieDb.getByIds(collectionName, ids);
       for (let i = 0; i < fullItems.length; i++) {
@@ -2829,7 +3001,10 @@ var _SyncEngine = class _SyncEngine {
         if (fullItem) {
           const delta = dirtyChangesMap.get(String(fullItem._id));
           if (delta) {
-            updates.push({ _id: fullItem._id, delta });
+            const currentServerRev = typeof fullItem._rev === "number" ? fullItem._rev : void 0;
+            updates.push({ _id: fullItem._id, delta, currentServerRev, fullItem });
+          } else {
+            skipped.push({ _id: String(fullItem._id), reason: "no-delta-for-fullitem" });
           }
         } else if (id != null) {
           const delta = dirtyChangesMap.get(String(id));
@@ -2837,23 +3012,69 @@ var _SyncEngine = class _SyncEngine {
             const reconstructed = __spreadProps(__spreadValues({}, delta), { _id: id });
             await this.dexieDb.save(collectionName, id, reconstructed);
             updates.push({ _id: id, delta });
+          } else {
+            skipped.push({ _id: String(id), reason: "no-delta-for-orphan" });
           }
+        } else {
+          skipped.push({ _id: "<null>", reason: "no-fullitem-no-id" });
         }
       }
       if (updates.length === 0) {
         console.warn(
-          `uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`
+          `uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`,
+          skipped
         );
+        if (this.callbacks.onUploadSkip) {
+          try {
+            this.callbacks.onUploadSkip({
+              collection: collectionName,
+              reason: "no-resolvable-items",
+              dirtyCount: dirtyChanges.length,
+              skippedIds: skipped.slice(0, 20).map((s) => s._id),
+              skipReasons: skipped.slice(0, 20),
+              calledFrom,
+              timestamp: /* @__PURE__ */ new Date()
+            });
+          } catch (err) {
+            console.error("onUploadSkip callback failed:", err);
+          }
+        }
         continue;
       }
+      if (skipped.length > 0 && this.callbacks.onUploadSkip) {
+        try {
+          this.callbacks.onUploadSkip({
+            collection: collectionName,
+            reason: "no-resolvable-items",
+            dirtyCount: dirtyChanges.length,
+            skippedIds: skipped.slice(0, 20).map((s) => s._id),
+            skipReasons: skipped.slice(0, 20),
+            calledFrom,
+            timestamp: /* @__PURE__ */ new Date()
+          });
+        } catch (err) {
+          console.error("onUploadSkip callback failed:", err);
+        }
+      }
       collectionBatches.push([{
         collection: collectionName,
         batch: {
           updates: updates.map((item) => {
-            const _a2 = item.delta, { _ts, _rev } = _a2, changes = __objRest(_a2, ["_ts", "_rev"]);
+            const _a2 = item.delta, { _ts, _rev: dirtyBaseRev } = _a2, changes = __objRest(_a2, ["_ts", "_rev"]);
+            const stripped = {};
+            for (const [k, v] of Object.entries(changes)) {
+              if (k.startsWith("_ts.") || k.startsWith("_rev.") || k.startsWith("_csq.")) continue;
+              stripped[k] = v;
+            }
+            const fixed = fixDotnetArrays(
+              stripped,
+              item.currentServerRev,
+              typeof dirtyBaseRev === "number" ? dirtyBaseRev : void 0
+            );
+            const cleanedChanges = translateBracketPathsToIndex(fixed, item.fullItem);
             return {
               _id: item._id,
-              update: changes
+              update: cleanedChanges
             };
           }),
           deletes: []
@@ -3752,6 +3973,8 @@ var _SyncedDb = class _SyncedDb {
     this.onWakeSync = config.onWakeSync;
     this.onEvictionStart = config.onEvictionStart;
     this.onEviction = config.onEviction;
+    this.onSaveIdMismatch = config.onSaveIdMismatch;
+    this.onUploadSkip = config.onUploadSkip;
     this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
     this.scopeExitLookbehindMs = (_f = config.scopeExitLookbehindMs) != null ? _f : 0;
     this.evictOnWake = (_g = config.evictOnWake) != null ? _g : false;
@@ -3888,7 +4111,8 @@ var _SyncedDb = class _SyncedDb {
         onServerWriteRequest: config.onServerWriteRequest,
         onServerWriteResult: config.onServerWriteResult,
         onFindNewerManyCall: config.onFindNewerManyCall,
-        onFindNewerManyResult: config.onFindNewerManyResult
+        onFindNewerManyResult: config.onFindNewerManyResult,
+        onUploadSkip: config.onUploadSkip
       },
       deps: {
         getSyncMetaCache: () => this.syncMetaCache,
@@ -4499,6 +4723,28 @@ var _SyncedDb = class _SyncedDb {
       );
       delete update._id;
     }
+    if ("_id" in update && update._id && String(update._id) !== String(id)) {
+      const updateKeys = Object.keys(update);
+      const stack = (() => {
+        try {
+          return new Error().stack;
+        } catch (e) {
+          return void 0;
+        }
+      })();
+      console.error(
+        `SyncedDb.save("${collection}", "${String(id)}"): update._id (${JSON.stringify(update._id)}) does NOT match id (${JSON.stringify(String(id))}). Stripped from update to prevent stuck-dirty bug. The caller likely passed a stale this._id while building update from a freshly-generated record. Data keys: [${updateKeys.join(", ")}]`
+      );
+      this.safeCallback(this.onSaveIdMismatch, {
+        collection,
+        id: String(id),
+        updateId: String(update._id),
+        updateKeys,
+        stack,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      delete update._id;
+    }
     update = _SyncedDb.stringifyObjectIds(update);
     const existing = await this.dexieDb.getById(collection, id);
     if (!existing && !((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly)) {

package/dist/src/db/SyncedDb.d.ts

@@ -52,6 +52,8 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onWakeSync?;
     private readonly onEvictionStart?;
     private readonly onEviction?;
+    private readonly onSaveIdMismatch?;
+    private readonly onUploadSkip?;
     private readonly evictStaleRecordsEveryHrs;
     private readonly scopeExitLookbehindMs;
     private readonly evictOnWake;

package/dist/src/db/types/managers.d.ts

@@ -261,6 +261,7 @@ export interface SyncEngineCallbacks {
     onServerWriteResult?: (info: ServerWriteResultInfo) => void;
     onFindNewerManyCall?: (info: FindNewerManyCallInfo) => void;
     onFindNewerManyResult?: (info: FindNewerManyResultInfo) => void;
+    onUploadSkip?: (info: import("../../types/I_SyncedDb").UploadSkipInfo) => void;
 }
 export interface SyncEngineDeps {
     getSyncMetaCache: () => Map<string, SyncMeta>;

package/dist/src/types/I_SyncedDb.d.ts

@@ -35,6 +35,62 @@ export interface InfrastructureErrorInfo {
     /** Timestamp when error occurred */
     timestamp: Date;
 }
+/**
+ * Payload za upload-skip callback. Sproži se, ko `uploadDirtyItems` najde
+ * dirty zapise v Dexie `_dirty_changes`, ampak iz njih ne more zgraditi
+ * resolve-able update batch (npr. fullItem manjka in `id` je null/undefined,
+ * ali `dirtyChangesMap.get` vrne undefined zaradi key mismatch-a).
+ *
+ * Production incident 2026-05-08 (etv/prvak/studenci/tackakp racuni stuck):
+ * 14 dirty zapisov nikoli ne pride na server, brez napake na rdb2/errors,
+ * `lastDirtySyncAt: null` (sentCount=0). Ta callback razkrije za katere
+ * konkretne `_id`-je se to dogaja.
+ */
+export interface UploadSkipInfo {
+    /** Collection kjer je skip nastal */
+    collection: string;
+    /** Razlog za skip */
+    reason: "no-resolvable-items" | "no-batches";
+    /** Število dirty zapisov v Dexie pred skip-om */
+    dirtyCount: number;
+    /** Konkretni _id-ji, ki so šli skozi skip pot (do 20) */
+    skippedIds: string[];
+    /** Razlog za vsak skipped _id (do 20) */
+    skipReasons: {
+        _id: string;
+        reason: "no-fullitem-no-id" | "no-delta-for-fullitem" | "no-delta-for-orphan";
+    }[];
+    /** calledFrom iz sync flow-a */
+    calledFrom?: string;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Payload za save() id-mismatch callback. Sproži se, ko caller pokliče
+ * `save(collection, id, update)` z `update._id` ki se NE ujema z `id`.
+ *
+ * Brez popravka bi addDirtyChange shranil entry.id = id, entry.changes._id =
+ * update._id; pri uploadu bi server dobil update._id, vrnil ack pod update._id,
+ * client bi poskušal clear pod id → ne ujema → dirty stuck forever.
+ *
+ * Library v save() avtomatsko strip-a `_id` iz update preden pokliče
+ * addDirtyChange. Callback je samo za telemetry/syslog/alerting — caller bug
+ * mora biti popravljen v aplikaciji.
+ */
+export interface SaveIdMismatchInfo {
+    /** Collection name */
+    collection: string;
+    /** id parameter passed to save() */
+    id: string;
+    /** _id field present in update object (mismatched) */
+    updateId: string;
+    /** Top-level keys of the update object (no values, no PII) */
+    updateKeys: string[];
+    /** Stack trace at the call site */
+    stack?: string;
+    /** Timestamp when mismatch detected */
+    timestamp: Date;
+}
 /**
  * Callback payload for server write requests (before sending)
  */
@@ -462,6 +518,29 @@ export interface SyncedDbConfig {
      * Client code can use this to show warnings, log telemetry, or adjust behavior.
      */
     onInfrastructureError?: (info: InfrastructureErrorInfo) => void;
+    /**
+     * Callback when `uploadDirtyItems` skips dirty entries (silent skip without
+     * sending to server). Used to diagnose stuck-dirty pattern where dirty
+     * exists but `sentCount === 0` (lastDirtySyncAt stays null).
+     *
+     * Production incident 2026-05-08 — 14 stuck racuni/protokoli on prod.
+     * Server has no record, no rdb2 error, dirty stays forever. This callback
+     * reveals which dirty entries hit which skip path.
+     */
+    onUploadSkip?: (info: UploadSkipInfo) => void;
+    /**
+     * Callback when `save(collection, id, update)` is called with `update._id`
+     * that does NOT match `id`. Library auto-strips `_id` from update to prevent
+     * the stuck-dirty bug, but the caller bug should be fixed in the app code.
+     *
+     * Use this callback for telemetry/syslog/alerting — the mismatch is silent
+     * data corruption (dirty stays forever) without observability.
+     *
+     * Production incident 2026-05-08 (zvitorepka, 3 stuck protokoli) was caused
+     * by `pages/protokol.vue` calling `save("protokoli", this._id, this.protokol)`
+     * where `this._id` and `this.protokol._id` had drifted apart.
+     */
+    onSaveIdMismatch?: (info: SaveIdMismatchInfo) => void;
     /**
      * Enable in-memory object metadata feature.
      * When true, collections with hasMetadata=true will have their metadata callbacks invoked

package/dist/src/utils/computeDiff.d.ts

@@ -23,23 +23,6 @@
  */
 /** Deep equality for values that may include Date, ObjectId, plain objects, arrays. */
 export declare function deepEquals(a: any, b: any): boolean;
-/**
- * Compute the minimal set of MongoDB dot-notation $set paths
- * that transform `existing` into `update` (only for keys present in `update`).
- *
- * @returns Record where keys are dot-notation paths and values are new values.
- *   Empty object means no changes.
- *
- * @example
- * existing = { koraki: [{ _id: "k1", diag: "old", ter: "x" }] }
- * update   = { koraki: [{ _id: "k1", diag: "new", ter: "x" }] }
- * → { "koraki.0.diag": "new" }
- *
- * @example
- * existing = { koraki: [{ _id: "k1" }] }
- * update   = { koraki: [{ _id: "k1" }, { _id: "k2", diag: "x" }] }
- * → { "koraki": [{ _id: "k1" }, { _id: "k2", diag: "x" }] }  // composition change
- */
 export declare function computeDiff(existing: Record<string, any> | null | undefined, update: Record<string, any>): Record<string, any>;
 /**
  * Detect whether a `changes` object uses dot-notation paths (new format)
@@ -49,6 +32,15 @@ export declare function computeDiff(existing: Record<string, any> | null | undef
  * to legacy Object.assign accumulation.
  */
 export declare function hasDotNotationPaths(changes: Record<string, any>): boolean;
+/**
+ * Tokenize a dot-notation path that may contain bracket-id segments.
+ *
+ * "postavke[A].kolicina"   → ["postavke", "[A]", "kolicina"]
+ * "koraki.0.diag"          → ["koraki", "0", "diag"]
+ * "stranka.gsm"            → ["stranka", "gsm"]
+ * "arr[A].sub[B].field"    → ["arr", "[A]", "sub", "[B]", "field"]
+ */
+export declare function tokenizePath(path: string): string[];
 /**
  * Smart-merge a single (path, value) entry into an accumulated dirty changes
  * object. Resolves three relationships between the new path and existing keys:

package/dist/src/utils/fixDotnetArrays.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Detects whether a dirty change key contains an array index segment,
+ * e.g. `postavke.0.a`, `koraki.5.diag`, `arr.10`. Returns `true` if the
+ * key has any segment matching `^\d+$` between dots (or trailing).
+ *
+ * Examples:
+ *   "stranka.gsm"          → false (nested object navigation)
+ *   "postavke.0.a"         → true  (array index 0)
+ *   "koraki.5.diag.text"   → true  (array index 5)
+ *   "koraki.5"             → true  (whole element at index 5)
+ *   "koraki"               → false (top-level, full array)
+ *   "_ts.t"                → false (no digit segment)
+ *   "arr.10"               → true  (multi-digit index)
+ */
+export declare function hasArrayIndexPath(key: string): boolean;
+/**
+ * TEMPORARY mitigation: when server has advanced past client's base _rev
+ * (i.e., the dirty was emitted against a stale snapshot of the record),
+ * drop dirty keys that contain array-index dot-notation. Their position
+ * may no longer correspond to the element the client intended to modify.
+ *
+ * @param changes - dirty payload to be uploaded (top-level _ts/_rev already stripped)
+ * @param serverRev - current server _rev for this record (from local Dexie main
+ *                    AFTER the download phase brought it up to date)
+ * @param baseRev - dirty entry's `baseRev` (the _rev when client emitted the diff)
+ * @returns cleaned `changes` with array-index paths dropped if `serverRev > baseRev`,
+ *          otherwise the input unchanged.
+ */
+export declare function fixDotnetArrays(changes: Record<string, any>, serverRev: number | undefined, baseRev: number | undefined): Record<string, any>;

package/dist/src/utils/translateBracketPaths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Translate every key in `changes` from bracket notation to mongo dot
+ * notation, resolving `[<_id>]` against the corresponding sub-array of
+ * `entity`. Drops keys whose `_id` cannot be resolved (= element was
+ * removed by another writer).
+ */
+export declare function translateBracketPathsToIndex(changes: Record<string, any>, entity: any): Record<string, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.155",
+  "version": "0.1.157",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",