@recordtimelabel/core 0.3.1 → 0.3.3

package/README.md

@@ -20,7 +20,7 @@ During local development an app can consume a sibling checkout with:
 For release builds, consume a fixed npm package, git tag, or private registry version so builds do not depend on a sibling folder path. The v2 gateway contract release is:
 
 ```json
-"@recordtimelabel/core": "0.3.1"
+"@recordtimelabel/core": "0.3.2"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -84,10 +84,15 @@ The core also normalizes and preserves these compatibility metadata fields:
 Deletion must be represented by tombstones or operations. Do not reintroduce the old heuristic that treats "local exists but cloud missing for more than five minutes" as deletion.
 
 `mergeLocalRemote` resolves deletions by `lifecycleGeneration`, in both directions: a tombstone or
-trash entry is dropped when either side carries that entity as active with a higher generation,
-which is what restore operations bump. A stale snapshot on either side therefore cannot re-delete
-an entity that was already restored, and consumers must not reimplement this reconciliation in an
-app-level wrapper.
+trash entry is dropped when either side carries that entity as active and newer, and restore
+operations are what bump the generation. When generations tie — an active copy written outside the
+delete/restore path — the active copy's own timestamp breaks the tie against `deletedAt`. A stale
+snapshot on either side therefore cannot re-delete an entity that was already restored.
+
+Consumers must not reimplement this reconciliation in an app-level wrapper. In particular, never
+clear a local tombstone just because the remote snapshot still carries the entity as active: that
+is presence-based inference, the same anti-pattern as the five-minute heuristic above, and it is not
+order-independent, so two clients using different rules will not converge on shared cloud data.
 
 ## Firestore v2 Gateway Contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",

package/src/index.js

@@ -5,7 +5,7 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.3.1';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.3.3';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
 export const RTL_MAX_REQUEST_BYTES = 256 * 1024;
@@ -220,7 +220,11 @@ const mergeTombstones = (left = {}, right = {}) => {
   const merged = { ...left };
   Object.entries(right).forEach(([id, tombstone]) => {
     const current = merged[id];
-    if (!current || toFiniteTimestamp(tombstone.deletedAt) >= toFiniteTimestamp(current.deletedAt)) {
+    const currentGeneration = Number(current?.lifecycleGeneration || 0);
+    const nextGeneration = Number(tombstone?.lifecycleGeneration || 0);
+    if (!current || nextGeneration > currentGeneration ||
+      (nextGeneration === currentGeneration &&
+        toFiniteTimestamp(tombstone.deletedAt) >= toFiniteTimestamp(current.deletedAt))) {
       merged[id] = { ...tombstone };
     }
   });
@@ -241,30 +245,42 @@ const mergeTrashEntries = (remoteEntries = {}, localEntries = {}) => {
   return merged;
 };
 
-const collectActiveLifecycleGenerations = (...states) => {
+const collectActiveLifecycleStates = (...states) => {
   const records = new Map();
   const folders = new Map();
-  const track = (target, id, entity) => {
+  const track = (target, id, entity, time) => {
     if (!id) return;
     const generation = Number(entity?.lifecycleGeneration || 0);
-    target.set(id, Math.max(generation, target.get(id) || 0));
+    const current = target.get(id);
+    if (current && (current.generation > generation ||
+      (current.generation === generation && current.time >= time))) return;
+    target.set(id, { generation, time });
   };
   states.forEach((state) => {
     Object.entries(state?.records || {}).forEach(([folderId, folderRecords]) => {
       if (VIRTUAL_FOLDER_IDS.has(normalizeId(folderId))) return;
-      toArray(folderRecords).forEach((record) => track(records, getRecordId(record), record));
+      toArray(folderRecords).forEach((record) => (
+        track(records, getRecordId(record), record, getRecordTime(record))
+      ));
     });
-    toArray(state?.folders).forEach((folder) => track(folders, normalizeId(folder?.id), folder));
+    toArray(state?.folders).forEach((folder) => (
+      track(folders, normalizeId(folder?.id), folder, getFolderTime(folder))
+    ));
   });
   return { records, folders };
 };
 
 /**
  * A tombstone or trash entry only stays valid while it describes the newest lifecycle event for
- * its entity. Once either side carries that entity as active with a higher lifecycleGeneration —
- * which restore operations bump — the deletion is stale and must be dropped, otherwise
- * mergeTombstones' union lets a stale snapshot re-delete a record that was already restored.
- * Generations default to 0, so legacy data never outranks a real tombstone.
+ * its entity. Once either side carries that entity as active and newer, the deletion is stale and
+ * must be dropped, otherwise mergeTombstones' union lets a stale snapshot re-delete a record that
+ * was already restored.
+ *
+ * "Newer" is decided by lifecycleGeneration first — restore operations bump it, and generations
+ * default to 0 so legacy data never outranks a real tombstone. Generations only tie when an active
+ * copy was written outside the delete/restore path, and there the active copy's own timestamp
+ * breaks the tie. That tie-break also makes this consistent with mergeLocalRemote's local-record
+ * loop, which already intends a record newer than `deletedAt` to survive its tombstone.
  */
 const dropSupersededLifecycleDeletions = ({
   deletedRecordTombstones = {},
@@ -272,9 +288,13 @@ const dropSupersededLifecycleDeletions = ({
   trashEntries = {},
   activeGenerations
 }) => {
-  const isSuperseded = (target, id, deletion) => (
-    (target.get(normalizeId(id)) || 0) > Number(deletion?.lifecycleGeneration || 0)
-  );
+  const isSuperseded = (target, id, deletion) => {
+    const active = target.get(normalizeId(id));
+    if (!active) return false;
+    const deletionGeneration = Number(deletion?.lifecycleGeneration || 0);
+    if (active.generation !== deletionGeneration) return active.generation > deletionGeneration;
+    return active.time > toFiniteTimestamp(deletion?.deletedAt);
+  };
   const nextRecordTombstones = { ...deletedRecordTombstones };
   Object.entries(nextRecordTombstones).forEach(([recordId, tombstone]) => {
     if (isSuperseded(activeGenerations.records, recordId, tombstone)) {
@@ -827,7 +847,8 @@ export const applyOperation = (state = {}, operation = {}) => {
       const recordSnapshot = payload.record && typeof payload.record === 'object'
         ? {...payload.record, id: recordId}
         : existingEntry?.record;
-      if (!recordSnapshot && nextState.trashEntries[`record:${recordId}`]) return normalized;
+      const trashEntryId = normalizeId(payload.trashEntryId) || `record:${recordId}`;
+      if (!recordSnapshot && nextState.trashEntries[trashEntryId]) return normalized;
       const deletedAt = toFiniteTimestamp(payload.deletedAt) || operationTime;
       const previousGeneration = Math.max(
         Number(recordSnapshot?.lifecycleGeneration || 0),
@@ -835,7 +856,6 @@ export const applyOperation = (state = {}, operation = {}) => {
       );
       const lifecycleGeneration = previousGeneration + 1;
       if (recordSnapshot) {
-        const trashEntryId = normalizeId(payload.trashEntryId) || `record:${recordId}`;
         nextState.trashEntries[trashEntryId] = {
           id: trashEntryId,
           kind: 'record',
@@ -951,6 +971,8 @@ export const applyOperation = (state = {}, operation = {}) => {
           entityId: folderId,
           batchId: normalizeId(payload.batchId) || operation.id || trashEntryId,
           originalFolderOrderIndex: Math.max(0, nextState.folderOrder.indexOf(folderId)),
+          // -1 records "was not in groupOrder", so restore does not invent a placement.
+          originalGroupOrderIndex: nextState.groupOrder.indexOf(folderId),
           lifecycleGeneration,
           deletedAt,
           purgeAt: toFiniteTimestamp(payload.purgeAt) || deletedAt + RTL_TRASH_RETENTION_MS,
@@ -1020,6 +1042,15 @@ export const applyOperation = (state = {}, operation = {}) => {
       );
       folderOrder.splice(restoreIndex, 0, folderId);
       nextState.folderOrder = folderOrder;
+      // folder.delete strips the id from groupOrder too, so restore has to put it back.
+      const originalGroupOrderIndex = Number.isInteger(trashEntry.originalGroupOrderIndex)
+        ? trashEntry.originalGroupOrderIndex
+        : -1;
+      if (originalGroupOrderIndex >= 0) {
+        const groupOrder = nextState.groupOrder.filter((id) => id !== folderId);
+        groupOrder.splice(Math.min(originalGroupOrderIndex, groupOrder.length), 0, folderId);
+        nextState.groupOrder = groupOrder;
+      }
       delete nextState.deletedFolderTombstones[folderId];
       nextState.records[folderId].forEach((record) => {
         delete nextState.deletedRecordTombstones[record.id];
@@ -1134,7 +1165,7 @@ export const mergeLocalRemote = ({
       local.deletedFolderTombstones
     ),
     trashEntries: mergeTrashEntries(remote.trashEntries, local.trashEntries),
-    activeGenerations: collectActiveLifecycleGenerations(remote, local)
+    activeGenerations: collectActiveLifecycleStates(remote, local)
   });
   const folders = mergeFolders(remote.folders, local.folders, deletedFolderTombstones);
   const folderIds = new Set(ensureFolders(folders).map((folder) => folder.id));
@@ -1569,6 +1600,29 @@ const cleanV2TrashDocument = (entry = {}, now) => {
   };
 };
 
+const buildV2LifecycleTombstoneDocuments = (
+  deletedRecordTombstones = {},
+  deletedFolderTombstones = {}
+) => {
+  const documents = {};
+  const append = (kind, tombstones) => {
+    Object.entries(normalizeTombstones(tombstones)).forEach(([entityId, tombstone]) => {
+      const id = `${kind}:${entityId}`;
+      documents[encodeURIComponent(id)] = {
+        id,
+        kind,
+        entityId,
+        lifecycleGeneration: Math.max(1, Number(tombstone.lifecycleGeneration || 1)),
+        deletedAt: toFiniteTimestamp(tombstone.deletedAt),
+        schemaVersion: 2
+      };
+    });
+  };
+  append('record', deletedRecordTombstones);
+  append('folder', deletedFolderTombstones);
+  return documents;
+};
+
 export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) => {
   const normalized = normalizeState(state || {});
   const now = resolveNow(options.now);
@@ -1604,6 +1658,11 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     if (trashDocument) trash[trashDocument.id] = trashDocument;
   });
 
+  const lifecycleTombstones = buildV2LifecycleTombstoneDocuments(
+    normalized.deletedRecordTombstones,
+    normalized.deletedFolderTombstones
+  );
+
   const root = {
     id: FIRESTORE_V2_SETTINGS_DOC_ID,
     schemaVersion: 2,
@@ -1627,6 +1686,7 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     records,
     folders,
     trash,
+    lifecycleTombstones,
     ops
   };
 };
@@ -1723,7 +1783,12 @@ export const buildFirestoreV2DocumentChangeSet = (
     nextDocuments?.trash,
     allowDeletes
   );
-  const hasCollectionChanges = [records, folders, trash, ops].some((changeSet) => (
+  const lifecycleTombstones = buildFirestoreV2CollectionChangeSet(
+    previousDocuments?.lifecycleTombstones,
+    nextDocuments?.lifecycleTombstones,
+    allowDeletes
+  );
+  const hasCollectionChanges = [records, folders, trash, lifecycleTombstones, ops].some((changeSet) => (
     Object.keys(changeSet.upserts).length > 0 || changeSet.deleteIds.length > 0
   ));
 
@@ -1733,6 +1798,7 @@ export const buildFirestoreV2DocumentChangeSet = (
     records,
     folders,
     trash,
+    lifecycleTombstones,
     ops
   };
 };
@@ -1742,11 +1808,54 @@ const removeV2Metadata = (data = {}) => {
   return rest;
 };
 
+/**
+ * lifecycleTombstones 子集合的文件形狀是 { id: 'record:abc', kind, entityId, lifecycleGeneration,
+ * deletedAt }，拆成 record / folder 兩張以 entityId 為鍵的表，好跟 root 上的舊資料合併。
+ */
+const splitLifecycleTombstoneDocuments = (value) => {
+  const records = {};
+  const folders = {};
+  mapValuesArray(value).forEach((entry) => {
+    const entityId = normalizeId(entry?.entityId);
+    const kind = normalizeId(entry?.kind);
+    const target = kind === 'folder' ? folders : kind === 'record' ? records : null;
+    if (!entityId || !target) return;
+    target[entityId] = {
+      id: entityId,
+      lifecycleGeneration: Math.max(1, Number(entry.lifecycleGeneration || 1)),
+      deletedAt: toFiniteTimestamp(entry.deletedAt)
+    };
+  });
+  return { records, folders };
+};
+
+/**
+ * root 的 tombstone 表已停止成長，但既有帳號上仍留著歷史資料，因此兩邊都要讀。同一個 id 同時出現時
+ * 以世代優先、時間次之，跟 dropSupersededLifecycleDeletions 的判準一致。
+ */
+const mergeLifecycleTombstoneSources = (legacy = {}, subcollection = {}) => {
+  const merged = normalizeTombstones(legacy);
+  Object.entries(normalizeTombstones(subcollection)).forEach(([id, tombstone]) => {
+    const current = merged[id];
+    const currentGeneration = Number(current?.lifecycleGeneration || 0);
+    const nextGeneration = Number(tombstone.lifecycleGeneration || 0);
+    if (!current || nextGeneration > currentGeneration ||
+      (nextGeneration === currentGeneration &&
+        toFiniteTimestamp(tombstone.deletedAt) >= toFiniteTimestamp(current.deletedAt))) {
+      merged[id] = tombstone;
+    }
+  });
+  return merged;
+};
+
 export const buildStateFromFirestoreV2Documents = (documents = {}, options = {}) => {
   const rootDoc = documents?.root ||
     documents?.settings?.[FIRESTORE_V2_SETTINGS_DOC_ID] ||
     documents?.settings ||
     {};
+  const lifecycleTombstones = splitLifecycleTombstoneDocuments(
+    documents?.lifecycleTombstones
+  );
   const records = {};
   mapValuesArray(documents?.records).forEach((recordDoc) => {
     const recordId = normalizeId(recordDoc?.id);
@@ -1804,8 +1913,14 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
     folderOrder: rootDoc.folderOrder || [],
     expandedGroups: rootDoc.expandedGroups || [],
     rtlSyncMeta: rootDoc.rtlSyncMeta || {},
-    deletedRecordTombstones: rootDoc.deletedRecordTombstones || {},
-    deletedFolderTombstones: rootDoc.deletedFolderTombstones || {},
+    deletedRecordTombstones: mergeLifecycleTombstoneSources(
+      rootDoc.deletedRecordTombstones,
+      lifecycleTombstones.records
+    ),
+    deletedFolderTombstones: mergeLifecycleTombstoneSources(
+      rootDoc.deletedFolderTombstones,
+      lifecycleTombstones.folders
+    ),
     trashEntries,
     lastModified: rootDoc.lastModified || 0
   });
@@ -2128,7 +2243,7 @@ export const flushPendingOperations = async ({
   }
 
   const syncTime = resolveNow(now);
-  const storageData = await storageAdapter.load(storageKeys);
+  const storageData = (await storageAdapter.load(storageKeys)) || {};
   const latestPendingOps = toArray(storageData.pendingOps);
   const requestedIds = new Set(requestedOperations.map((operation) => operation?.id).filter(Boolean));
   const pendingOpsForPayload = latestPendingOps.filter((operation) => requestedIds.has(operation?.id));
@@ -2606,16 +2721,23 @@ const rtlOperationFolderId = (operation = {}) => normalizeId(
 const rtlOperationTrashEntryId = (operation = {}) => normalizeId(
   operation?.payload?.trashEntryId || operation?.payload?.id
 );
+const rtlLifecycleTombstoneDocumentId = (kind, entityId) => (
+  encodeURIComponent(`${kind}:${normalizeId(entityId)}`)
+);
 const rtlCloneDocuments = (documents = {}) => ({
   root: clone(documents.root || null),
   records: clone(documents.records || {}),
   folders: clone(documents.folders || {}),
   trash: clone(documents.trash || {}),
+  lifecycleTombstones: clone(documents.lifecycleTombstones || {}),
   ops: {}
 });
 const rtlMergeOrder = (...orders) => normalizeOrder(orders.flatMap((order) => toArray(order)));
-const rtlNormalizeGroupOrder = (order) => rtlMergeOrder(order)
-  .filter((id) => id.startsWith('group-'));
+/**
+ * Group order ids are opaque to this package — mergeLocalRemote deliberately stops filtering them,
+ * so the planner must not drop ids on a prefix guess either.
+ */
+const rtlNormalizeGroupOrder = (order) => rtlMergeOrder(order);
 const rtlPayloadOrder = (operation, keys) => {
   for (const key of keys) {
     if (Array.isArray(operation?.payload?.[key])) return operation.payload[key];
@@ -2795,13 +2917,17 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
   const folderIds = new Set();
   const folderDeleteIds = new Set();
   const trashEntryIds = new Set();
+  const lifecycleTombstoneIds = new Set();
   toArray(operations).filter(Boolean).forEach((operation) => {
     const payload = operation.payload || {};
     switch (operation.type) {
       case OPERATION_TYPES.RECORD_CREATE:
       case OPERATION_TYPES.RECORD_MOVE: {
         const recordId = rtlOperationRecordId(operation);
-        if (recordId) recordIds.add(recordId);
+        if (recordId) {
+          recordIds.add(recordId);
+          lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('record', recordId));
+        }
         folderIds.add(safeFolderId(
           payload.targetFolderId || payload.folderId || payload.record?.folderId
         ));
@@ -2810,7 +2936,10 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
       case OPERATION_TYPES.RECORD_UPDATE:
       case OPERATION_TYPES.RECORD_DELETE: {
         const recordId = rtlOperationRecordId(operation);
-        if (recordId) recordIds.add(recordId);
+        if (recordId) {
+          recordIds.add(recordId);
+          lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('record', recordId));
+        }
         break;
       }
       case OPERATION_TYPES.RECORD_RESTORE:
@@ -2826,7 +2955,10 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
       case OPERATION_TYPES.FOLDER_UPDATE:
       case OPERATION_TYPES.FOLDER_DELETE: {
         const folderId = rtlOperationFolderId(operation);
-        if (folderId) folderIds.add(folderId);
+        if (folderId) {
+          folderIds.add(folderId);
+          lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('folder', folderId));
+        }
         if (folderId && operation.type === OPERATION_TYPES.FOLDER_DELETE) {
           folderDeleteIds.add(folderId);
         }
@@ -2836,7 +2968,7 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
         break;
     }
   });
-  return {recordIds, folderIds, folderDeleteIds, trashEntryIds};
+  return {recordIds, folderIds, folderDeleteIds, trashEntryIds, lifecycleTombstoneIds};
 };
 
 export const extendFirestoreV2OperationReadPlanWithRecords = (readPlan, records = {}) => {
@@ -2844,7 +2976,8 @@ export const extendFirestoreV2OperationReadPlanWithRecords = (readPlan, records
     recordIds: new Set(readPlan?.recordIds || []),
     folderIds: new Set(readPlan?.folderIds || []),
     folderDeleteIds: new Set(readPlan?.folderDeleteIds || []),
-    trashEntryIds: new Set(readPlan?.trashEntryIds || [])
+    trashEntryIds: new Set(readPlan?.trashEntryIds || []),
+    lifecycleTombstoneIds: new Set(readPlan?.lifecycleTombstoneIds || [])
   };
   Object.values(records || {}).forEach((record) => {
     next.folderIds.add(safeFolderId(record?.folderId));
@@ -2857,18 +2990,40 @@ export const extendFirestoreV2OperationReadPlanWithTrash = (readPlan, trashEntri
     recordIds: new Set(readPlan?.recordIds || []),
     folderIds: new Set(readPlan?.folderIds || []),
     folderDeleteIds: new Set(readPlan?.folderDeleteIds || []),
-    trashEntryIds: new Set(readPlan?.trashEntryIds || [])
+    trashEntryIds: new Set(readPlan?.trashEntryIds || []),
+    lifecycleTombstoneIds: new Set(readPlan?.lifecycleTombstoneIds || [])
   };
   Object.values(trashEntries || {}).forEach((entry) => {
-    if (entry?.kind === 'record') next.folderIds.add(safeFolderId(entry.originalFolderId));
+    const entityId = normalizeId(entry?.entityId);
+    if (entry?.kind === 'record') {
+      next.folderIds.add(safeFolderId(entry.originalFolderId));
+      if (entityId) {
+        next.lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('record', entityId));
+      }
+    } else if (entry?.kind === 'folder' && entityId) {
+      next.lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('folder', entityId));
+    }
   });
   next.folderIds.add(DEFAULT_FOLDER_ID);
   return next;
 };
 
-const rtlApplyOperationToPartialDocuments = ({root, records, folders, trash, operation, now}) => {
+const rtlApplyOperationToPartialDocuments = ({
+  root,
+  records,
+  folders,
+  trash,
+  lifecycleTombstones,
+  operation,
+  now
+}) => {
   const {state} = buildStateFromFirestoreV2Documents({
-    root: root || {}, records: records || {}, folders: folders || {}, trash: trash || {}, ops: {}
+    root: root || {},
+    records: records || {},
+    folders: folders || {},
+    trash: trash || {},
+    lifecycleTombstones: lifecycleTombstones || {},
+    ops: {}
   });
   const nextState = applyRecordTimeLabelOperation(state, operation);
   return {
@@ -2934,6 +3089,7 @@ export const planFirestoreV2OperationChanges = ({
     const folderId = rtlOperationFolderId(operation);
     let applied = null;
     let reason = null;
+    let lifecycleTombstoneId = null;
 
     switch (operation.type) {
       case OPERATION_TYPES.RECORD_CREATE: {
@@ -2996,25 +3152,28 @@ export const planFirestoreV2OperationChanges = ({
         });
         const recordDocument = applied.documents.records[recordId];
         if (!recordDocument) { reason = 'record_not_found'; break; }
+        const candidateRoot = clone(applied.documents.root);
+        const candidateFolders = clone(nextDocuments.folders);
         const targetFolder = rtlEnsureTargetFolder({
-          root: nextDocuments.root,
-          folders: nextDocuments.folders,
+          root: candidateRoot,
+          folders: candidateFolders,
           localState: normalizedLocalState,
           folderId: targetFolderId,
           now: operationNow
         });
         if (!targetFolder) { reason = 'folder_not_found'; break; }
-        rtlSetRoot(nextDocuments.root, applied.documents.root);
-        nextDocuments.records[recordId] = recordDocument;
-        if (nextDocuments.folders[sourceFolderId]) {
-          nextDocuments.folders[sourceFolderId].recordOrder = rtlMergeOrder(
-            nextDocuments.folders[sourceFolderId].recordOrder
+        if (candidateFolders[sourceFolderId]) {
+          candidateFolders[sourceFolderId].recordOrder = rtlMergeOrder(
+            candidateFolders[sourceFolderId].recordOrder
           ).filter((id) => id !== recordId);
         }
         targetFolder.recordOrder = [
           ...rtlMergeOrder(targetFolder.recordOrder).filter((id) => id !== recordId),
           recordId
         ];
+        rtlSetRoot(nextDocuments.root, candidateRoot);
+        nextDocuments.folders = candidateFolders;
+        nextDocuments.records[recordId] = recordDocument;
         changed = true;
         break;
       }
@@ -3034,6 +3193,7 @@ export const planFirestoreV2OperationChanges = ({
       }
       case OPERATION_TYPES.RECORD_DELETE: {
         if (!recordId) { reason = 'missing_record_id'; break; }
+        lifecycleTombstoneId = rtlLifecycleTombstoneDocumentId('record', recordId);
         const sourceFolderId = safeFolderId(nextDocuments.records[recordId]?.folderId);
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         rtlSetRoot(nextDocuments.root, applied.documents.root);
@@ -3062,6 +3222,7 @@ export const planFirestoreV2OperationChanges = ({
           reason = restoredRecordId ? 'already_exists' : 'missing_record_id';
           break;
         }
+        lifecycleTombstoneId = rtlLifecycleTombstoneDocumentId('record', restoredRecordId);
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         const restoredRecord = applied.documents.records[restoredRecordId];
         if (!restoredRecord) { reason = 'restore_conflict'; break; }
@@ -3072,10 +3233,12 @@ export const planFirestoreV2OperationChanges = ({
         rtlSetRoot(nextDocuments.root, applied.documents.root);
         nextDocuments.records[restoredRecordId] = restoredRecord;
         delete nextDocuments.trash[trashEntryId];
+        const previousRecordOrder = rtlMergeOrder(targetFolder.recordOrder);
+        const restoreIndex = Number(trashEntry.originalRecordIndex || 0);
         targetFolder.recordOrder = rtlMergeOrder(
-          targetFolder.recordOrder.slice(0, Number(trashEntry.originalRecordIndex || 0)),
+          previousRecordOrder.slice(0, restoreIndex),
           [restoredRecordId],
-          targetFolder.recordOrder.slice(Number(trashEntry.originalRecordIndex || 0))
+          previousRecordOrder.slice(restoreIndex)
         );
         changed = true;
         break;
@@ -3139,9 +3302,7 @@ export const planFirestoreV2OperationChanges = ({
           ));
         } else if (operation.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE) {
           appliedRoot.expandedGroups = rtlMergeOrder(
-            rtlPayloadOrder(operation, ['expandedGroups', 'groupIds', 'order', 'ids']),
-            nextDocuments.root.expandedGroups,
-            normalizedLocalState.expandedGroups
+            rtlPayloadOrder(operation, ['expandedGroups', 'groupIds', 'order', 'ids'])
           );
         }
         rtlSetRoot(nextDocuments.root, appliedRoot);
@@ -3151,6 +3312,14 @@ export const planFirestoreV2OperationChanges = ({
       default:
         reason = 'unsupported_operation';
     }
+    if (applied && !reason && lifecycleTombstoneId) {
+      const nextTombstone = applied.documents.lifecycleTombstones?.[lifecycleTombstoneId];
+      if (nextTombstone) {
+        nextDocuments.lifecycleTombstones[lifecycleTombstoneId] = clone(nextTombstone);
+      } else {
+        delete nextDocuments.lifecycleTombstones[lifecycleTombstoneId];
+      }
+    }
     operationResults.push({
       id: operation.id || null,
       type: operation.type || null,
@@ -3184,7 +3353,7 @@ export const planFirestoreV2OperationChanges = ({
  * Counts all billable writes before a transaction reserves quota.
  */
 export const estimateFirestoreV2WriteUnits = (changes = {}, overhead = 3) => {
-  const collectionWrites = ['records', 'folders', 'trash', 'ops'].reduce((count, key) => (
+  const collectionWrites = ['records', 'folders', 'trash', 'lifecycleTombstones', 'ops'].reduce((count, key) => (
     count + Object.keys(changes?.[key]?.upserts || {}).length +
       toArray(changes?.[key]?.deleteIds).length
   ), 0);
@@ -3206,6 +3375,15 @@ const rtlStateRecordMap = (state) => {
   return records;
 };
 
+const rtlStateRecordOrders = (state) => {
+  const orders = new Map();
+  Object.entries(normalizeState(state || {}).records).forEach(([folderId, entries]) => {
+    if (VIRTUAL_FOLDER_IDS.has(folderId)) return;
+    orders.set(folderId, toArray(entries).map(getRecordId).filter(Boolean));
+  });
+  return orders;
+};
+
 const rtlComparableJson = (value) => JSON.stringify(value || {});
 
 /**
@@ -3224,6 +3402,11 @@ export const buildOperationsFromSnapshotDiff = ({
   const nextRecords = rtlStateRecordMap(next);
   const previousFolders = new Map(previous.folders.map((folder) => [folder.id, folder]));
   const nextFolders = new Map(next.folders.map((folder) => [folder.id, folder]));
+  const deletedFolderIds = new Set(
+    [...previousFolders.keys()].filter((folderId) => (
+      !RTL_PROTECTED_FOLDER_IDS.has(folderId) && !nextFolders.has(folderId)
+    ))
+  );
   const drafts = [];
   const bulkDrafts = [];
 
@@ -3255,18 +3438,29 @@ export const buildOperationsFromSnapshotDiff = ({
   });
 
   previousRecords.forEach((entry, recordId) => {
-    if (!nextRecords.has(recordId)) {
+    if (!nextRecords.has(recordId) && !deletedFolderIds.has(entry.folderId)) {
       drafts.push({type: OPERATION_TYPES.RECORD_DELETE, payload: {recordId, deletedAt: now}});
     }
   });
 
-  previousFolders.forEach((folder, folderId) => {
-    if (!RTL_PROTECTED_FOLDER_IDS.has(folderId) && !nextFolders.has(folderId)) {
-      bulkDrafts.push({
-        type: OPERATION_TYPES.FOLDER_DELETE,
-        payload: {folderId, deletedAt: now}
-      });
-    }
+  // Create prepends and move appends records, so neither operation can reproduce an arbitrary
+  // snapshot position. Emit the complete target order whenever a folder's order differs; preceding
+  // create/move/delete operations make the planner's fallback order contain only live target ids.
+  const previousRecordOrders = rtlStateRecordOrders(previous);
+  rtlStateRecordOrders(next).forEach((nextOrder, folderId) => {
+    const previousOrder = toArray(previousRecordOrders.get(folderId));
+    if (nextOrder.length === 0 || rtlComparableJson(previousOrder) === rtlComparableJson(nextOrder)) return;
+    drafts.push({
+      type: OPERATION_TYPES.RECORD_REORDER,
+      payload: {folderId, recordIds: nextOrder}
+    });
+  });
+
+  deletedFolderIds.forEach((folderId) => {
+    bulkDrafts.push({
+      type: OPERATION_TYPES.FOLDER_DELETE,
+      payload: {folderId, deletedAt: now}
+    });
   });
 
   if (rtlComparableJson(previous.folderOrder) !== rtlComparableJson(next.folderOrder)) {