cry-db 2.4.48 → 2.5.0

package/dist/mongo.mjs

@@ -897,11 +897,17 @@ export class Mongo extends Db {
                         inserted: [],
                         updated: [],
                         deleted: [],
+                        mustRefresh: [],
                     }
                 };
                 const batchData = [];
                 const errors = [];
                 const warnings = [];
+                // Per-update flag: did the client send a field cry-db resolves
+                // server-side (SEQ_*/__hashed__)? Captured BEFORE the bulk sequence
+                // resolution and per-update hashing mutate the updates in place, so
+                // the placeholders are still observable here.
+                const updateResolvedFlags = (updates !== null && updates !== void 0 ? updates : []).map(u => this._hasSequenceFields(u.update) || this._hasHashedKeys(u.update));
                 // Handle sequences in updates before processing
                 if (updates === null || updates === void 0 ? void 0 : updates.length) {
                     const updatesWithSeq = updates.filter(u => this._hasSequenceFields(u.update));
@@ -911,7 +917,7 @@ export class Mongo extends Db {
                 }
                 // Process updates (with upsert) in parallel
                 if (updates === null || updates === void 0 ? void 0 : updates.length) {
-                    const updatePromises = updates.map(async ({ _id, update }) => {
+                    const updatePromises = updates.map(async ({ _id, _rev: clientRev, update }, idx) => {
                         var _a, _b;
                         try {
                             const objectId = Mongo._toId(_id);
@@ -923,10 +929,10 @@ export class Mongo extends Db {
                             const processed = this._applyBracketProcessing(processedBase);
                             if (processed.warnings) {
                                 for (const w of processed.warnings) {
-                                    warnings.push({
-                                        _id: String(_id),
-                                        error: `dropped nested-bracket ${w.op} path "${w.path}" = ${JSON.stringify(w.value)}`,
-                                    });
+                                    const msg = w.kind === 'overlap'
+                                        ? `same-id overlap at "${w.path}" — terminal-bracket value ${JSON.stringify(w.value)} sets the element base; sub-field overlay applies on top`
+                                        : `dropped nested-bracket ${w.op} path "${w.path}" = ${JSON.stringify(w.value)}`;
+                                    warnings.push({ _id: String(_id), error: msg });
                                 }
                             }
                             const opts = {
@@ -945,6 +951,19 @@ export class Mongo extends Db {
                                 // Determine if this was an insert or update based on lastErrorObject
                                 const wasInsert = !((_b = res.lastErrorObject) === null || _b === void 0 ? void 0 : _b.updatedExisting);
                                 const operation = wasInsert ? 'insert' : 'update';
+                                // mustRefresh: the client must replace its local copy when cry-db
+                                // resolved a field (SEQ_*/__hashed__) OR a concurrent external write
+                                // advanced the stored `_rev` beyond this write (gap > the +1 this write
+                                // applied). An omitted `_rev` (clientRev → 0) forces a refresh — the
+                                // old-client fallback. Built from a sanitized clone (hash never leaks).
+                                const writtenRev = res.value._rev;
+                                const inc = this.revisions ? 1 : 0;
+                                const externallyModified = !wasInsert
+                                    && typeof writtenRev === 'number'
+                                    && (writtenRev - inc) > (clientRev !== null && clientRev !== void 0 ? clientRev : 0);
+                                const mustRefresh = (updateResolvedFlags[idx] || externallyModified)
+                                    ? this._buildMustRefreshRecord(res.value)
+                                    : undefined;
                                 // Inserts surface the full doc (query fields must reach the client).
                                 // Updates always go through _buildPublishDelta so bracket keys collapse
                                 // to top-level parent array slices read straight from the post-update
@@ -953,7 +972,7 @@ export class Mongo extends Db {
                                     ? res.value
                                     : this._buildPublishDelta(res.value, inputUpdate, false);
                                 this._processReturnedObject(retObj);
-                                return { success: true, _id, data: retObj, operation, wasInsert, rawUpdate: wasInsert ? undefined : inputUpdate };
+                                return { success: true, _id, data: retObj, operation, wasInsert, rawUpdate: wasInsert ? undefined : inputUpdate, mustRefresh };
                             }
                             return { success: false, _id, error: 'Operation failed' };
                         }
@@ -975,6 +994,8 @@ export class Mongo extends Db {
                             else {
                                 result.results.updated.push(dbEntity);
                             }
+                            if (res.mustRefresh)
+                                result.results.mustRefresh.push(res.mustRefresh);
                             const item = { operation: res.operation, data: res.data };
                             // rawUpdate is meaningful only for the update branch — inserts publish the full doc.
                             if (!res.wasInsert)
@@ -988,7 +1009,7 @@ export class Mongo extends Db {
                 }
                 // Process deletes in parallel
                 if (deletes === null || deletes === void 0 ? void 0 : deletes.length) {
-                    const deletePromises = deletes.map(async ({ _id }) => {
+                    const deletePromises = deletes.map(async ({ _id, _rev: clientRev }) => {
                         try {
                             const objectId = Mongo._toId(_id);
                             if (!this.softdelete) {
@@ -997,8 +1018,16 @@ export class Mongo extends Db {
                                     .collection(collection)
                                     .findOneAndDelete({ _id: objectId }, this._sessionOpt());
                                 if (res) {
+                                    // Hard delete applies no `_rev` increment: the removed doc's `_rev`
+                                    // exceeding the client's base means an external write landed first.
+                                    // Omitted `_rev` (clientRev → 0) forces a refresh — old-client fallback.
+                                    const externallyModified = typeof res._rev === 'number'
+                                        && res._rev > (clientRev !== null && clientRev !== void 0 ? clientRev : 0);
+                                    const mustRefresh = externallyModified
+                                        ? this._buildMustRefreshRecord(res)
+                                        : undefined;
                                     this._processReturnedObject(res);
-                                    return { success: true, _id, data: res, operation: 'delete' };
+                                    return { success: true, _id, data: res, operation: 'delete', mustRefresh };
                                 }
                                 return { success: false, _id, error: 'Document not found' };
                             }
@@ -1018,8 +1047,16 @@ export class Mongo extends Db {
                                     .collection(collection)
                                     .findOneAndUpdate({ _id: objectId }, del, opts);
                                 if (res) {
+                                    // Soft delete applied a +1 `_rev` increment: a gap beyond that +1
+                                    // means an external write modified the record before this delete.
+                                    // Omitted `_rev` (clientRev → 0) forces a refresh — old-client fallback.
+                                    const externallyModified = typeof res._rev === 'number'
+                                        && (res._rev - 1) > (clientRev !== null && clientRev !== void 0 ? clientRev : 0);
+                                    const mustRefresh = externallyModified
+                                        ? this._buildMustRefreshRecord(res)
+                                        : undefined;
                                     this._processReturnedObject(res);
-                                    return { success: true, _id, data: res, operation: 'delete' };
+                                    return { success: true, _id, data: res, operation: 'delete', mustRefresh };
                                 }
                                 return { success: false, _id, error: 'Document not found' };
                             }
@@ -1038,6 +1075,8 @@ export class Mongo extends Db {
                                 _deleted: res.data._deleted,
                             };
                             result.results.deleted.push(dbEntity);
+                            if (res.mustRefresh)
+                                result.results.mustRefresh.push(res.mustRefresh);
                             batchData.push({ operation: res.operation, data: res.data });
                         }
                         else if (!res.success && res.error) {
@@ -2297,6 +2336,17 @@ export class Mongo extends Db {
             out._id = wholerecord._id;
         return out;
     }
+    /**
+     * Build a `mustRefresh` entry: a full, sanitized clone of the post-write
+     * document the client must adopt locally. Sanitization strips `__hashed__`
+     * (the hash never leaves the server), other `__`-internal keys, and the
+     * configured `findNewerRemoveFields`/`removeFieldsAlways` — matching what a
+     * read/publish exposes. `_id`/`_rev`/`_ts` are preserved. Clones first so
+     * the caller's `res.value`/`res` is left intact for the publish payload.
+     */
+    _buildMustRefreshRecord(fullDoc) {
+        return this._processReturnedObject(cloneDeep(fullDoc), this._findNewerRemoveFields);
+    }
     _shouldAuditCollection(db, col) {
         if (!this.auditing)
             return false;
@@ -3042,6 +3092,46 @@ export class Mongo extends Db {
         processOp('$unset');
         return extractedAny ? result : undefined;
     }
+    /**
+     * Build the filter + concat + map+switch expression that transforms an
+     * array according to a FieldOps spec. Used both at the top level (in
+     * `_applyBracketProcessing`'s main pipeline) and recursively from
+     * `_buildElementMergeExpr` to compose nested-array transformations
+     * inside an element overlay.
+     *
+     * `baseInputPath` is a mongo field path string (e.g. `"$koraki"` for
+     * top-level, `"$$el.postavke"` for nested). It MUST be a string so the
+     * generated expression can read the existing array via `$ifNull`.
+     */
+    static _buildArrayTransformExpr(baseInputPath, ops) {
+        const dedupedRemoveIds = Mongo._normalizeBracketIds(Array.from(new Set(ops.removeIds)));
+        const filteredInput = {
+            $filter: {
+                input: { $ifNull: [baseInputPath, []] },
+                as: 'el',
+                cond: { $not: { $in: ['$$el._id', dedupedRemoveIds] } },
+            },
+        };
+        const concatExpr = {
+            $concatArrays: [filteredInput, { $literal: ops.insertElements }],
+        };
+        if (ops.elementOps.size === 0)
+            return concatExpr;
+        const branches = [];
+        for (const [id, elOps] of ops.elementOps.entries()) {
+            branches.push({
+                case: { $eq: ['$$el._id', Mongo._normalizeBracketId(id)] },
+                then: Mongo._buildElementMergeExpr('$$el', elOps),
+            });
+        }
+        return {
+            $map: {
+                input: concatExpr,
+                as: 'el',
+                in: { $switch: { branches, default: '$$el' } },
+            },
+        };
+    }
     /**
      * Build an aggregation expression that produces a transformed copy of an
      * element, applying the given sets/unsets and (optionally) a whole-element
@@ -3055,6 +3145,9 @@ export class Mongo extends Db {
      *   `$$REMOVE` inside `$mergeObjects` does NOT drop the field (mongo treats
      *   it as a missing value and falls through to the previous operand), so
      *   the explicit kv-filter is required.
+     * - `nestedArrayOps`: per-array-field FieldOps for nested-bracket support.
+     *   Each entry produces a `$mergeObjects` overlay that replaces the named
+     *   field with the recursive output of `_buildArrayTransformExpr`.
      *
      * The returned expression is suitable as the `in:` argument of `$map`.
      */
@@ -3062,12 +3155,65 @@ export class Mongo extends Db {
         const hasSets = Object.keys(ops.sets).length > 0;
         const hasUnsets = ops.unsets.length > 0;
         const hasReplace = ops.replace !== undefined;
-        if (!hasSets && !hasUnsets && !hasReplace)
+        const hasNestedArrayOps = !!(ops.nestedArrayOps && ops.nestedArrayOps.size > 0);
+        // Helper: layer the nested-array overlays on top of an existing
+        // merge expression. Used at every return point so nested-bracket
+        // sub-field updates and nested terminal-bracket inserts apply
+        // regardless of whether the outer element also has sets/unsets/replace.
+        //
+        // Removes-only entries (no insertElements, no elementOps) are
+        // conditionally applied — only if the source array exists. This
+        // matches mongo's native "no-op on missing field" semantics for
+        // $pull / $unset and avoids creating spurious empty arrays on
+        // elements that didn't originally carry the field.
+        const wrapWithNestedArrays = (expr, basePath) => {
+            if (!hasNestedArrayOps)
+                return expr;
+            const alwaysOverlay = {};
+            const conditionalEntries = [];
+            for (const [field, nestedFieldOps] of ops.nestedArrayOps.entries()) {
+                const transform = Mongo._buildArrayTransformExpr(`${basePath}.${field}`, nestedFieldOps);
+                const hasInserts = nestedFieldOps.insertElements.length > 0;
+                const hasOverlays = nestedFieldOps.elementOps.size > 0;
+                if (hasInserts || hasOverlays) {
+                    alwaysOverlay[field] = transform;
+                }
+                else {
+                    conditionalEntries.push({ field, transform });
+                }
+            }
+            let result = Object.keys(alwaysOverlay).length > 0
+                ? { $mergeObjects: [expr, alwaysOverlay] }
+                : expr;
+            for (const { field, transform } of conditionalEntries) {
+                result = {
+                    $cond: [
+                        { $isArray: `${basePath}.${field}` },
+                        { $mergeObjects: [result, { [field]: transform }] },
+                        result,
+                    ],
+                };
+            }
+            return result;
+        };
+        if (!hasSets && !hasUnsets && !hasReplace && !hasNestedArrayOps) {
             return baseExpr;
+        }
+        if (!hasSets && !hasUnsets && !hasReplace && hasNestedArrayOps) {
+            return wrapWithNestedArrays(baseExpr, baseExpr);
+        }
         if (!hasSets && !hasUnsets) {
             // Pure replace — embed as literal so client-supplied field names like
             // "_id" don't get interpreted as field paths.
-            return { $literal: ops.replace };
+            const replaceExpr = { $literal: ops.replace };
+            if (!hasNestedArrayOps)
+                return replaceExpr;
+            return {
+                $let: {
+                    vars: { replaced: replaceExpr },
+                    in: wrapWithNestedArrays('$$replaced', '$$replaced'),
+                },
+            };
         }
         const root = { directs: {}, nested: {}, unsets: [] };
         const walkInsert = (path, isUnset, value) => {
@@ -3131,11 +3277,11 @@ export class Mongo extends Db {
             return {
                 $let: {
                     vars: { replaced: { $literal: ops.replace } },
-                    in: overlayExpr,
+                    in: wrapWithNestedArrays(overlayExpr, '$$replaced'),
                 },
             };
         }
-        return buildOverlay(root, baseExpr);
+        return wrapWithNestedArrays(buildOverlay(root, baseExpr), baseExpr);
     }
     /**
      * Translate an update doc's `$inc` and `$currentDate` operators into
@@ -3209,9 +3355,42 @@ export class Mongo extends Db {
         this._validateAndAutoFillTerminalBracketValues(update);
         const inserts = this._extractArrayInserts(update);
         const removes = this._extractArrayRemoves(update);
-        // Pure sub-field updates only (no inserts, no removes) — keep on legacy
-        // arrayFilters path (faster, smaller payload, doesn't fight $inc/$currentDate).
-        if (!inserts && !removes) {
+        // Detect NESTED terminal-bracket paths (2+ brackets, last token is bracket
+        // with array value or in $unset). Mongo cannot express these via
+        // `arrayFilters` — both `$set arr.$[f0].sub.$[f1]` AND `$unset arr.$[f0].sub.$[f1]`
+        // collide with sibling sub-field paths on the same `arr.$[f0].sub.$[f1]`
+        // positional. Force pipeline form so the nested processing below can
+        // recursively express filter+concat+map+switch inside an element overlay.
+        const hasNestedTerminalBracket = (op) => {
+            if (!op)
+                return false;
+            for (const k of Object.keys(op)) {
+                const tokens = Mongo._tokenizePath(k);
+                if (tokens.length < 2)
+                    continue;
+                let bracketCount = 0;
+                for (const t of tokens) {
+                    if (t.length >= 2 && t.charCodeAt(0) === 91 && t.charCodeAt(t.length - 1) === 93) {
+                        bracketCount++;
+                    }
+                }
+                if (bracketCount < 2)
+                    continue;
+                const last = tokens[tokens.length - 1];
+                if (last.length >= 2 && last.charCodeAt(0) === 91 && last.charCodeAt(last.length - 1) === 93) {
+                    return true;
+                }
+            }
+            return false;
+        };
+        const $setEarlyForNested = update.$set;
+        const $unsetEarlyForNested = update.$unset;
+        const hasNestedTerminal = hasNestedTerminalBracket($setEarlyForNested) || hasNestedTerminalBracket($unsetEarlyForNested);
+        // Pure sub-field updates only (no inserts, no removes, no nested-terminal) —
+        // keep on legacy arrayFilters path (faster, smaller payload, doesn't fight
+        // $inc/$currentDate). Nested sub-field paths like `arr[A].sub[B].field`
+        // ARE supported via nested arrayFilters here.
+        if (!inserts && !removes && !hasNestedTerminal) {
             const arrayFilters = this._extractArrayFilters(update);
             return arrayFilters ? { update, arrayFilters } : { update };
         }
@@ -3277,52 +3456,42 @@ export class Mongo extends Db {
         // Extract single-bracket sub-field paths so we can express them as pipeline
         // stages instead of arrayFilters (mongo forbids arrayFilters on pipelines).
         const subFieldOps = this._extractArraySubFieldUpdates(update);
-        // NESTED-bracket paths (e.g. `arr[A].sub[B].field`) can't be expressed
-        // in the pipeline form alongside terminal-bracket inserts (mongo forbids
-        // arrayFilters on pipelines). Drop them, collect as warnings so callers
-        // can surface them, and let the rest of the update proceed.
+        // Build the recursive fieldOps structure. Top-level (single-bracket)
+        // inserts/removes/sub-field updates have already been extracted by
+        // the dedicated helpers; ingest them now. Remaining bracket-containing
+        // keys in $set/$unset are NESTED (e.g. `arr[A].sub[B].field`) and get
+        // processed below into the recursive `nestedArrayOps` structure.
         const warnings = [];
-        const stripNestedBracket = (op, opName) => {
-            if (!op)
-                return;
-            for (const k of Object.keys(op)) {
-                if (k.indexOf('[') >= 0) {
-                    warnings.push({ path: k, value: op[k], op: opName });
-                    delete op[k];
-                }
-            }
-        };
-        stripNestedBracket(update.$set, '$set');
-        stripNestedBracket(update.$unset, '$unset');
-        if (warnings.length > 0) {
-            fjLog.warn('cry-db: dropping NESTED-bracket sub-field paths combined with terminal-bracket array operations (not expressible in pipeline form):', warnings);
-        }
-        if (update.$set && Object.keys(update.$set).length === 0)
-            delete update.$set;
-        if (update.$unset && Object.keys(update.$unset).length === 0)
-            delete update.$unset;
         const fieldOps = new Map();
-        const ensureField = (field) => {
-            if (!fieldOps.has(field))
-                fieldOps.set(field, { removeIds: [], insertElements: [], elementOps: new Map() });
-            return fieldOps.get(field);
+        const ensureField = (container, field) => {
+            if (!container.has(field))
+                container.set(field, { removeIds: [], insertElements: [], elementOps: new Map() });
+            return container.get(field);
+        };
+        const ensureElement = (fops, id) => {
+            if (!fops.elementOps.has(id))
+                fops.elementOps.set(id, { sets: {}, unsets: [], nestedArrayOps: new Map() });
+            const elOps = fops.elementOps.get(id);
+            if (!elOps.nestedArrayOps)
+                elOps.nestedArrayOps = new Map();
+            return elOps;
         };
         if (inserts) {
             for (const ins of inserts) {
-                const ops = ensureField(ins.field);
+                const ops = ensureField(fieldOps, ins.field);
                 ops.removeIds.push(...ins.ids);
                 ops.insertElements.push(...ins.elements);
             }
         }
         if (removes) {
             for (const rm of removes) {
-                const ops = ensureField(rm.field);
+                const ops = ensureField(fieldOps, rm.field);
                 ops.removeIds.push(...rm.ids);
             }
         }
         if (subFieldOps) {
             for (const [field, idMap] of subFieldOps.entries()) {
-                const ops = ensureField(field);
+                const ops = ensureField(fieldOps, field);
                 for (const [id, elOps] of idMap.entries()) {
                     // Sub-field updates are applied AFTER the post-concat array (i.e.
                     // they overlay BOTH existing-kept elements and freshly-inserted
@@ -3330,10 +3499,173 @@ export class Mongo extends Db {
                     // element with the insert as its base and the sub-field update
                     // overriding matching fields. Order: non-bracket → terminal-bracket
                     // insert/remove → sub-field overlay.
-                    ops.elementOps.set(id, elOps);
+                    const target = ensureElement(ops, id);
+                    Object.assign(target.sets, elOps.sets);
+                    target.unsets.push(...elOps.unsets);
+                    if (elOps.replace !== undefined)
+                        target.replace = elOps.replace;
+                }
+            }
+        }
+        // Process REMAINING bracket-containing keys (multi-bracket / nested).
+        // Each path adds entries to the recursive nestedArrayOps structure.
+        const processNestedPaths = (op, opName) => {
+            if (!op)
+                return;
+            const remaining = {};
+            for (const path of Object.keys(op)) {
+                if (path.indexOf('[') < 0) {
+                    remaining[path] = op[path];
+                    continue;
+                }
+                const tokens = Mongo._tokenizePath(path);
+                const brackets = [];
+                for (let i = 0; i < tokens.length; i++) {
+                    const t = tokens[i];
+                    if (t.length >= 2 && t.charCodeAt(0) === 91 && t.charCodeAt(t.length - 1) === 93) {
+                        brackets.push({ idx: i, id: Mongo._unquoteBracketId(t, path) });
+                    }
+                }
+                if (brackets.length < 2) {
+                    // Single-bracket: extractors above should have handled it; if it
+                    // remained, it's malformed (e.g. empty parent). Drop with warning.
+                    warnings.push({ path, value: op[path], op: opName, kind: 'dropped' });
+                    continue;
+                }
+                // Walk all but the innermost bracket — descend through nestedArrayOps.
+                let currentMap = fieldOps;
+                let ok = true;
+                for (let bi = 0; bi < brackets.length - 1; bi++) {
+                    const bracket = brackets[bi];
+                    const fieldStart = bi === 0 ? 0 : brackets[bi - 1].idx + 1;
+                    const fieldName = tokens.slice(fieldStart, bracket.idx).join('.');
+                    if (!fieldName) {
+                        ok = false;
+                        break;
+                    }
+                    const fops = ensureField(currentMap, fieldName);
+                    const elOps = ensureElement(fops, bracket.id);
+                    currentMap = elOps.nestedArrayOps;
+                }
+                if (!ok) {
+                    warnings.push({ path, value: op[path], op: opName, kind: 'dropped' });
+                    continue;
+                }
+                const lastB = brackets[brackets.length - 1];
+                const fieldStart = brackets[brackets.length - 2].idx + 1;
+                const innerFieldName = tokens.slice(fieldStart, lastB.idx).join('.');
+                const restPath = tokens.slice(lastB.idx + 1).join('.');
+                if (!innerFieldName) {
+                    warnings.push({ path, value: op[path], op: opName, kind: 'dropped' });
+                    continue;
+                }
+                const innerFOps = ensureField(currentMap, innerFieldName);
+                const value = op[path];
+                if (opName === '$set') {
+                    if (restPath === '') {
+                        if (Array.isArray(value)) {
+                            innerFOps.removeIds.push(lastB.id);
+                            innerFOps.insertElements.push(...value);
+                        }
+                        else {
+                            // Whole-element replace at nested level.
+                            const elOps = ensureElement(innerFOps, lastB.id);
+                            elOps.replace = value;
+                        }
+                    }
+                    else {
+                        const elOps = ensureElement(innerFOps, lastB.id);
+                        elOps.sets[restPath] = value;
+                    }
+                }
+                else {
+                    // $unset
+                    if (restPath === '') {
+                        innerFOps.removeIds.push(lastB.id);
+                    }
+                    else {
+                        const elOps = ensureElement(innerFOps, lastB.id);
+                        elOps.unsets.push(restPath);
+                    }
+                }
+            }
+            update[opName] = remaining;
+            if (Object.keys(remaining).length === 0)
+                delete update[opName];
+        };
+        processNestedPaths(update.$set, '$set');
+        processNestedPaths(update.$unset, '$unset');
+        // Detect same-id overlap at NESTED levels: a "new base" (terminal-array
+        // insert OR whole-element replace) targeting the same `_id` as a
+        // sub-field set/unset on the same element. Both apply — new base goes
+        // first, sub-field overlay applies on top — but the unusual overlap is
+        // surfaced as a `kind: 'overlap'` warning so callers know.
+        //
+        // Two flavors at the source of the "new base":
+        //   - terminal-array (`arr[id]: [...]`): id ends up in `removeIds`
+        //     AND `insertElements`. The matching element in elementOps will
+        //     carry sets/unsets if a same-id sub-field path was also present.
+        //   - whole-element replace (`arr[id]: {...}`): id ends up in
+        //     `elementOps[id].replace`. Sets/unsets co-locate on the same
+        //     entry when a same-id sub-field path was also present.
+        //
+        // Top-level same-id case is the same semantic but stays silent — it's
+        // a documented, supported merge for backwards compat.
+        const detectOverlaps = (container, parentPathRepr) => {
+            for (const [field, fops] of container.entries()) {
+                const fullField = parentPathRepr ? `${parentPathRepr}.${field}` : field;
+                const isNested = parentPathRepr !== '';
+                // Flavor 1: terminal-array insert + sub-field on same id.
+                const removeIdSet = new Set(fops.removeIds);
+                if (isNested) {
+                    for (const id of fops.removeIds) {
+                        const elOps = fops.elementOps.get(id);
+                        if (!elOps)
+                            continue;
+                        const hasOps = Object.keys(elOps.sets).length > 0
+                            || elOps.unsets.length > 0
+                            || elOps.replace !== undefined;
+                        if (hasOps) {
+                            const insertedEl = fops.insertElements.find((e) => String(e._id) === id);
+                            warnings.push({
+                                path: `${fullField}[${id}]`,
+                                value: insertedEl,
+                                op: '$set',
+                                kind: 'overlap',
+                            });
+                        }
+                    }
+                }
+                // Flavor 2: whole-element replace + sub-field on same id.
+                // Skip ids already covered by Flavor 1 above (avoid double-warn).
+                for (const [id, elOps] of fops.elementOps.entries()) {
+                    if (isNested && !removeIdSet.has(id)) {
+                        const hasReplace = elOps.replace !== undefined;
+                        const hasSetsOrUnsets = Object.keys(elOps.sets).length > 0
+                            || elOps.unsets.length > 0;
+                        if (hasReplace && hasSetsOrUnsets) {
+                            warnings.push({
+                                path: `${fullField}[${id}]`,
+                                value: elOps.replace,
+                                op: '$set',
+                                kind: 'overlap',
+                            });
+                        }
+                    }
+                    if (elOps.nestedArrayOps && elOps.nestedArrayOps.size > 0) {
+                        detectOverlaps(elOps.nestedArrayOps, `${fullField}[${id}]`);
+                    }
                 }
             }
+        };
+        detectOverlaps(fieldOps, '');
+        if (warnings.length > 0) {
+            fjLog.warn('cry-db: bracket-by-_id warnings:', warnings);
         }
+        if (update.$set && Object.keys(update.$set).length === 0)
+            delete update.$set;
+        if (update.$unset && Object.keys(update.$unset).length === 0)
+            delete update.$unset;
         const pipeline = [];
         if (update.$set && Object.keys(update.$set).length > 0) {
             pipeline.push({ $set: update.$set });
@@ -3344,52 +3676,13 @@ export class Mongo extends Db {
         // Translate $inc / $currentDate so revisions (_rev/_ts) still update in pipeline form.
         for (const stage of Mongo._drainIncAndCurrentDateToPipelineStages(update))
             pipeline.push(stage);
+        // Build one $set stage per parent array field. The filter+concat+map+switch
+        // expression (with potentially recursive nested-array transforms inside
+        // per-element overlays) is built by `_buildArrayTransformExpr`.
         for (const [field, ops] of fieldOps.entries()) {
-            const dedupedRemoveIds = Mongo._normalizeBracketIds(Array.from(new Set(ops.removeIds)));
-            const filteredInput = {
-                $filter: {
-                    input: { $ifNull: [`$${field}`, []] },
-                    as: 'el',
-                    cond: { $not: { $in: ['$$el._id', dedupedRemoveIds] } },
-                },
-            };
-            // `$literal` wraps the insert array as opaque data, so mongo's
-            // expression parser does not interpret user-supplied field names
-            // with `.` or `$` as expression paths (legitimate-as-stored mongo
-            // doc keys would otherwise crash with
-            // `FieldPath field names may not contain '.'`).
-            const concatExpr = {
-                $concatArrays: [filteredInput, { $literal: ops.insertElements }],
-            };
-            // Apply sub-field updates to the FULL post-concat array (existing-kept
-            // AND newly inserted), so when an update mixes a terminal-bracket
-            // replace (`arr[id]: [el]`) and sub-field updates (`arr[id].field: x`)
-            // for the SAME id, the sub-field update overrides matching fields on
-            // the inserted element. This matches the user-facing semantics
-            // "bracketed fields apply after non-bracketed" applied transitively:
-            // sub-field updates are the most-specific bracket form, so they are
-            // applied LAST.
-            let resultExpr = concatExpr;
-            if (ops.elementOps.size > 0) {
-                // Build $switch with one branch per (id → merged element).
-                const branches = [];
-                for (const [id, elOps] of ops.elementOps.entries()) {
-                    branches.push({
-                        case: { $eq: ['$$el._id', Mongo._normalizeBracketId(id)] },
-                        then: Mongo._buildElementMergeExpr('$$el', elOps),
-                    });
-                }
-                resultExpr = {
-                    $map: {
-                        input: concatExpr,
-                        as: 'el',
-                        in: { $switch: { branches, default: '$$el' } },
-                    },
-                };
-            }
             pipeline.push({
                 $set: {
-                    [field]: resultExpr,
+                    [field]: Mongo._buildArrayTransformExpr(`$${field}`, ops),
                 },
             });
         }