@recordtimelabel/core 0.2.0 → 0.3.0

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.2.0"
+"@recordtimelabel/core": "0.3.0"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -48,9 +48,10 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `validateRecordTimeLabelOperationBatch(body)`
 - `buildFirestoreV2OperationReadPlan(operations)`
 - `extendFirestoreV2OperationReadPlanWithRecords(readPlan, records)`
+- `extendFirestoreV2OperationReadPlanWithTrash(readPlan, trashEntries)`
 - `planFirestoreV2OperationChanges({ documents, operations, localState, now })`
 - `estimateFirestoreV2WriteUnits(changes, overhead)`
-- `buildOperationsFromSnapshotDiff({ previousState, nextState, now, operationIdPrefix, batchSize })`
+- `buildOperationsFromSnapshotDiff({ previousState, nextState, now, operationIdPrefix, batchSize })`（一般操作在 `batches`，`folder.delete` 在 `bulkOperations`）
 - `RTL_SYNC_PROTOCOL_VERSION`
 - `hasMeaningfulRecordTimeLabelCloudState(data, options)`
 - `buildRecordTimeLabelContentFingerprint(data)`
@@ -59,6 +60,8 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `RECORD_TIMELABEL_SYNC_MODES`
 - `createOperation(type, payload, options)`
 - `OPERATION_TYPES`
+- `getActiveTrashEntries(entries, now)`
+- `RTL_TRASH_RETENTION_MS`
 
 ## Firestore v1 Compatibility
 
@@ -76,6 +79,7 @@ The core also normalizes and preserves these compatibility metadata fields:
 - `rtlSyncMeta`
 - `deletedRecordTombstones`
 - `deletedFolderTombstones`
+- `trashEntries`
 
 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.
 
@@ -86,6 +90,8 @@ The package exposes platform-neutral v2 document helpers so app adapters can sha
 - root document `users/{uid}/recordTimeLabel/main`: settings, order arrays, tombstones, and sync metadata
 - `users/{uid}/recordTimeLabel/main/records/{recordId}`: flattened per-record documents with `folderId`
 - `users/{uid}/recordTimeLabel/main/folders/{folderId}`: per-folder documents
+- `users/{uid}/recordTimeLabel/main/trash/{trashEntryId}`: 30-day record/folder snapshots
+- `users/{uid}/recordTimeLabel/main/lifecycleTombstones/{id}`: content-free anti-revival markers
 - `users/{uid}/recordTimeLabel/main/ops/{opId}`: pending operation documents
 
 The v2 validator, bounded read planner, pure mutation planner, cost estimator, and snapshot-diff batch builder are also platform-neutral. They do not import Firebase and do not perform network writes. Functions and clients must use this package instead of maintaining app-specific planner copies.

package/package.json

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

package/src/index.js

@@ -5,25 +5,32 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.2.0';
-export const RTL_SYNC_PROTOCOL_VERSION = 1;
+export const RECORD_TIMELABEL_CORE_VERSION = '0.3.0';
+export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
 export const RTL_MAX_REQUEST_BYTES = 256 * 1024;
 export const RTL_MAX_TARGET_WRITES = 100;
+export const RTL_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
 export const OPERATION_TYPES = Object.freeze({
   RECORD_CREATE: 'record.create',
   RECORD_UPDATE: 'record.update',
   RECORD_MOVE: 'record.move',
   RECORD_DELETE: 'record.delete',
+  RECORD_RESTORE: 'record.restore',
   RECORD_REORDER: 'record.reorder',
   FOLDER_CREATE: 'folder.create',
   FOLDER_UPDATE: 'folder.update',
   FOLDER_DELETE: 'folder.delete',
+  FOLDER_RESTORE: 'folder.restore',
   FOLDER_REORDER: 'folder.reorder',
   GROUP_REORDER: 'group.reorder',
   EXPANDED_GROUPS_UPDATE: 'expandedGroups.update',
-  SETTINGS_UPDATE: 'settings.update'
+  SETTINGS_UPDATE: 'settings.update',
+  TRASH_PURGE: 'trash.purge',
+  TRASH_PURGE_BATCH: 'trash.purgeBatch',
+  TRASH_RESTORE_BATCH: 'trash.restoreBatch',
+  TRASH_EMPTY: 'trash.empty'
 });
 
 const ORDER_OPERATION_TYPES = new Set([
@@ -46,12 +53,31 @@ export const RECORD_TIMELABEL_CLOUD_SCHEMAS = Object.freeze({
 export const FIRESTORE_V2_SETTINGS_DOC_ID = 'main';
 
 const toArray = (value) => (Array.isArray(value) ? value : []);
-const clone = (value) => {
-  if (value === undefined || value === null) return value;
-  return JSON.parse(JSON.stringify(value));
+const clone = (value, seen = new WeakMap()) => {
+  if (value === undefined || value === null || typeof value !== 'object') return value;
+  if (value instanceof Date) return new Date(value.getTime());
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) {
+    return value;
+  }
+  if (seen.has(value)) return seen.get(value);
+  const copy = Array.isArray(value) ? [] : {};
+  seen.set(value, copy);
+  Reflect.ownKeys(value).forEach((key) => {
+    copy[key] = clone(value[key], seen);
+  });
+  return copy;
 };
 
 const toFiniteTimestamp = (value) => {
+  if (value && typeof value.toMillis === 'function') {
+    const millis = Number(value.toMillis());
+    return Number.isFinite(millis) ? millis : 0;
+  }
+  if (value && Number.isFinite(Number(value.seconds))) {
+    return (Number(value.seconds) * 1000) +
+      Math.floor(Number(value.nanoseconds || 0) / 1e6);
+  }
   if (typeof value === 'number') {
     return Number.isFinite(value) ? value : 0;
   }
@@ -157,6 +183,39 @@ const normalizeTombstones = (value) => {
   }, {});
 };
 
+const normalizeTrashEntries = (value) => {
+  if (!value) return {};
+  const entries = Array.isArray(value)
+    ? value.map((entry) => [entry?.id, entry])
+    : Object.entries(value);
+
+  return entries.reduce((result, [rawId, rawEntry]) => {
+    if (!rawEntry || typeof rawEntry !== 'object') return result;
+    const id = normalizeId(rawId || rawEntry.id);
+    const kind = normalizeId(rawEntry.kind);
+    const entityId = normalizeId(rawEntry.entityId);
+    if (!id || !entityId || !new Set(['record', 'folder']).has(kind)) return result;
+    const deletedAt = toFiniteTimestamp(rawEntry.deletedAt);
+    const purgeAt = toFiniteTimestamp(rawEntry.purgeAt) ||
+      ((deletedAt || Date.now()) + RTL_TRASH_RETENTION_MS);
+    result[id] = {
+      ...clone(rawEntry),
+      id,
+      kind,
+      entityId,
+      batchId: normalizeId(rawEntry.batchId) || id,
+      lifecycleGeneration: Math.max(1, Number(rawEntry.lifecycleGeneration || 1)),
+      deletedAt: deletedAt || Date.now(),
+      purgeAt
+    };
+    return result;
+  }, {});
+};
+
+export const getActiveTrashEntries = (value, now = Date.now()) => Object.values(
+  normalizeTrashEntries(value)
+).filter((entry) => toFiniteTimestamp(entry.purgeAt) > toFiniteTimestamp(now));
+
 const mergeTombstones = (left = {}, right = {}) => {
   const merged = { ...left };
   Object.entries(right).forEach(([id, tombstone]) => {
@@ -168,6 +227,20 @@ const mergeTombstones = (left = {}, right = {}) => {
   return merged;
 };
 
+const mergeTrashEntries = (remoteEntries = {}, localEntries = {}) => {
+  const merged = normalizeTrashEntries(remoteEntries);
+  Object.entries(normalizeTrashEntries(localEntries)).forEach(([id, entry]) => {
+    const current = merged[id];
+    const currentVersion = Number(current?.lifecycleGeneration || 0);
+    const nextVersion = Number(entry.lifecycleGeneration || 0);
+    if (!current || nextVersion > currentVersion ||
+      (nextVersion === currentVersion && toFiniteTimestamp(entry.deletedAt) > toFiniteTimestamp(current.deletedAt))) {
+      merged[id] = entry;
+    }
+  });
+  return merged;
+};
+
 const resolveRecordFolderId = (folderId, record = {}) => {
   const candidates = [
     record.folderId,
@@ -245,13 +318,9 @@ export const normalizeRecords = (records = {}, options = {}) => {
       delete normalizedRecord.sortIndex;
 
       const tombstone = tombstones[id];
-      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= getRecordTime(normalizedRecord)) {
-        return;
-      }
+      if (tombstone) return;
       const folderTombstone = folderTombstones[targetFolderId];
-      if (folderTombstone && toFiniteTimestamp(folderTombstone.deletedAt) >= getRecordTime(normalizedRecord)) {
-        return;
-      }
+      if (folderTombstone) return;
 
       if (!normalized[targetFolderId]) normalized[targetFolderId] = [];
 
@@ -352,9 +421,7 @@ const mergeFolders = (remoteFolders = [], localFolders = [], deletedFolderTombst
     if (!id) return;
 
     const tombstone = deletedFolderTombstones[id];
-    if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= getFolderTime(folder)) {
-      return;
-    }
+    if (tombstone) return;
 
     const current = byId.get(id);
     if (!current) {
@@ -390,9 +457,7 @@ export const normalizeState = (input = {}) => {
   const deletedFolderTombstones = normalizeTombstones(input.deletedFolderTombstones);
   const folders = ensureFolders(input.folders).filter((folder) => {
     const tombstone = deletedFolderTombstones[folder.id];
-    if (!tombstone) return true;
-    const folderTime = toFiniteTimestamp(folder.updatedAt || folder.createdAt);
-    return folderTime > toFiniteTimestamp(tombstone.deletedAt);
+    return !tombstone;
   });
   const records = ensureRecordFolders(
     normalizeRecords(input.records, { deletedRecordTombstones, deletedFolderTombstones }),
@@ -412,6 +477,7 @@ export const normalizeState = (input = {}) => {
     },
     deletedRecordTombstones,
     deletedFolderTombstones,
+    trashEntries: normalizeTrashEntries(input.trashEntries),
     lastModified: toFiniteTimestamp(input.lastModified || input.updatedAt || input.lastUpdated)
   };
 };
@@ -434,6 +500,7 @@ export const hasMeaningfulRecordTimeLabelCloudState = (input = {}, options = {})
     Object.keys(state.settings || {}).length > 0 ||
     Object.keys(state.deletedRecordTombstones || {}).length > 0 ||
     Object.keys(state.deletedFolderTombstones || {}).length > 0 ||
+    Object.keys(state.trashEntries || {}).length > 0 ||
     hasNonDefaultGroupOrder ||
     state.folderOrder.length > 0 ||
     state.expandedGroups.length > 0;
@@ -449,7 +516,8 @@ export const buildRecordTimeLabelContentFingerprint = (input = {}) => {
     folderOrder: state.folderOrder,
     expandedGroups: state.expandedGroups,
     deletedRecordTombstones: state.deletedRecordTombstones,
-    deletedFolderTombstones: state.deletedFolderTombstones
+    deletedFolderTombstones: state.deletedFolderTombstones,
+    trashEntries: state.trashEntries
   });
 };
 
@@ -590,10 +658,7 @@ export const applyOperation = (state = {}, operation = {}) => {
       const recordId = normalizeId(record.id || payload.recordId);
       if (!recordId) return normalized;
       const tombstone = nextState.deletedRecordTombstones[recordId];
-      const recordTime = getRecordTime(record) || operationTime;
-      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= recordTime) {
-        return normalized;
-      }
+      if (tombstone) return normalized;
 
       const folderId = safeFolderId(payload.folderId || record.folderId);
       const cleanedRecord = {
@@ -698,20 +763,85 @@ export const applyOperation = (state = {}, operation = {}) => {
     case OPERATION_TYPES.RECORD_DELETE: {
       const recordId = normalizeId(payload.recordId || payload.id);
       if (!recordId) return normalized;
+      const existingEntry = findRecordEntry(nextState.records, recordId);
+      const recordSnapshot = payload.record && typeof payload.record === 'object'
+        ? {...payload.record, id: recordId}
+        : existingEntry?.record;
+      if (!recordSnapshot && nextState.trashEntries[`record:${recordId}`]) return normalized;
+      const deletedAt = toFiniteTimestamp(payload.deletedAt) || operationTime;
+      const previousGeneration = Math.max(
+        Number(recordSnapshot?.lifecycleGeneration || 0),
+        Number(nextState.deletedRecordTombstones[recordId]?.lifecycleGeneration || 0)
+      );
+      const lifecycleGeneration = previousGeneration + 1;
+      if (recordSnapshot) {
+        const trashEntryId = normalizeId(payload.trashEntryId) || `record:${recordId}`;
+        nextState.trashEntries[trashEntryId] = {
+          id: trashEntryId,
+          kind: 'record',
+          entityId: recordId,
+          batchId: normalizeId(payload.batchId) || operation.id || trashEntryId,
+          originalFolderId: safeFolderId(payload.folderId || existingEntry?.folderId),
+          originalRecordIndex: Number.isInteger(payload.originalRecordIndex)
+            ? payload.originalRecordIndex
+            : Math.max(0, Number(existingEntry?.index || 0)),
+          lifecycleGeneration,
+          deletedAt,
+          purgeAt: toFiniteTimestamp(payload.purgeAt) || deletedAt + RTL_TRASH_RETENTION_MS,
+          payload: {record: {...recordSnapshot, lifecycleGeneration}}
+        };
+      }
       nextState.records = removeRecordById(nextState.records, recordId);
       nextState.deletedRecordTombstones[recordId] = {
         id: recordId,
-        deletedAt: payload.deletedAt || operationTime,
+        deletedAt,
+        lifecycleGeneration,
         clientId: operation.clientId || payload.clientId || null,
         operationId: operation.id || null
       };
       break;
     }
 
+    case OPERATION_TYPES.RECORD_RESTORE: {
+      const trashEntryId = normalizeId(payload.trashEntryId) ||
+        `record:${normalizeId(payload.recordId || payload.id)}`;
+      const trashEntry = nextState.trashEntries[trashEntryId];
+      if (!trashEntry || trashEntry.kind !== 'record') return normalized;
+      if (toFiniteTimestamp(trashEntry.purgeAt) <= operationTime) return normalized;
+      if (payload.expectedGeneration &&
+        Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) return normalized;
+      const recordId = normalizeId(trashEntry.entityId);
+      if (!recordId || findRecordEntry(nextState.records, recordId)) return normalized;
+      const recordSnapshot = trashEntry.payload?.record;
+      if (!recordSnapshot) return normalized;
+      const originalFolderId = safeFolderId(trashEntry.originalFolderId);
+      const targetFolderId = nextState.folders.some((folder) => folder.id === originalFolderId)
+        ? originalFolderId
+        : DEFAULT_FOLDER_ID;
+      const lifecycleGeneration = Number(trashEntry.lifecycleGeneration || 0) + 1;
+      const restoredRecord = {
+        ...recordSnapshot,
+        id: recordId,
+        lifecycleGeneration,
+        updatedAt: operationTime
+      };
+      const targetRecords = [...toArray(nextState.records[targetFolderId])];
+      const restoreIndex = Math.min(
+        Math.max(0, Number(trashEntry.originalRecordIndex || 0)),
+        targetRecords.length
+      );
+      targetRecords.splice(restoreIndex, 0, restoredRecord);
+      nextState.records[targetFolderId] = targetRecords;
+      delete nextState.trashEntries[trashEntryId];
+      delete nextState.deletedRecordTombstones[recordId];
+      break;
+    }
+
     case OPERATION_TYPES.FOLDER_CREATE: {
       const folder = payload.folder && typeof payload.folder === 'object' ? { ...payload.folder } : null;
       const folderId = normalizeId(folder?.id || payload.folderId);
       if (!folderId) return normalized;
+      if (nextState.deletedFolderTombstones[folderId]) return normalized;
       const existingIndex = nextState.folders.findIndex((item) => item.id === folderId);
       const nextFolder = {
         ...(folder || {}),
@@ -742,16 +872,146 @@ export const applyOperation = (state = {}, operation = {}) => {
     case OPERATION_TYPES.FOLDER_DELETE: {
       const folderId = normalizeId(payload.folderId || payload.id);
       if (!folderId || folderId === 'all' || folderId === DEFAULT_FOLDER_ID) return normalized;
+      const folderSnapshot = payload.folder && typeof payload.folder === 'object'
+        ? {...payload.folder, id: folderId}
+        : nextState.folders.find((folder) => folder.id === folderId);
+      const folderRecords = toArray(payload.records || nextState.records[folderId]).map((record) => ({...record}));
+      if (!folderSnapshot && nextState.trashEntries[`folder:${folderId}`]) return normalized;
+      const deletedAt = toFiniteTimestamp(payload.deletedAt) || operationTime;
+      const previousGeneration = Math.max(
+        Number(folderSnapshot?.lifecycleGeneration || 0),
+        Number(nextState.deletedFolderTombstones[folderId]?.lifecycleGeneration || 0)
+      );
+      const lifecycleGeneration = previousGeneration + 1;
+      if (folderSnapshot) {
+        const trashEntryId = normalizeId(payload.trashEntryId) || `folder:${folderId}`;
+        nextState.trashEntries[trashEntryId] = {
+          id: trashEntryId,
+          kind: 'folder',
+          entityId: folderId,
+          batchId: normalizeId(payload.batchId) || operation.id || trashEntryId,
+          originalFolderOrderIndex: Math.max(0, nextState.folderOrder.indexOf(folderId)),
+          lifecycleGeneration,
+          deletedAt,
+          purgeAt: toFiniteTimestamp(payload.purgeAt) || deletedAt + RTL_TRASH_RETENTION_MS,
+          payload: {
+            folder: {...folderSnapshot, lifecycleGeneration},
+            records: folderRecords.map((record) => ({
+              ...record,
+              lifecycleGeneration: Number(record.lifecycleGeneration || 0) + 1
+            }))
+          }
+        };
+      }
       nextState.folders = nextState.folders.filter((folder) => folder.id !== folderId);
       delete nextState.records[folderId];
       nextState.folderOrder = nextState.folderOrder.filter((id) => id !== folderId);
       nextState.groupOrder = nextState.groupOrder.filter((id) => id !== folderId);
       nextState.deletedFolderTombstones[folderId] = {
         id: folderId,
-        deletedAt: payload.deletedAt || operationTime,
+        deletedAt,
+        lifecycleGeneration,
         clientId: operation.clientId || payload.clientId || null,
         operationId: operation.id || null
       };
+      folderRecords.forEach((record) => {
+        const recordId = getRecordId(record);
+        if (!recordId) return;
+        nextState.deletedRecordTombstones[recordId] = {
+          id: recordId,
+          folderId,
+          deletedAt,
+          lifecycleGeneration: Number(record.lifecycleGeneration || 0) + 1,
+          clientId: operation.clientId || payload.clientId || null,
+          operationId: operation.id || null
+        };
+      });
+      break;
+    }
+
+    case OPERATION_TYPES.FOLDER_RESTORE: {
+      const trashEntryId = normalizeId(payload.trashEntryId) ||
+        `folder:${normalizeId(payload.folderId || payload.id)}`;
+      const trashEntry = nextState.trashEntries[trashEntryId];
+      if (!trashEntry || trashEntry.kind !== 'folder') return normalized;
+      if (toFiniteTimestamp(trashEntry.purgeAt) <= operationTime) return normalized;
+      if (payload.expectedGeneration &&
+        Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) return normalized;
+      const folderId = normalizeId(trashEntry.entityId);
+      if (!folderId || nextState.folders.some((folder) => folder.id === folderId)) return normalized;
+      const folderSnapshot = trashEntry.payload?.folder;
+      if (!folderSnapshot) return normalized;
+      const lifecycleGeneration = Number(trashEntry.lifecycleGeneration || 0) + 1;
+      nextState.folders.push({
+        ...folderSnapshot,
+        id: folderId,
+        lifecycleGeneration,
+        updatedAt: operationTime
+      });
+      nextState.records[folderId] = toArray(trashEntry.payload?.records).map((record) => ({
+        ...record,
+        lifecycleGeneration: Number(record.lifecycleGeneration || 0) + 1,
+        updatedAt: operationTime
+      }));
+      const folderOrder = nextState.folderOrder.filter((id) => id !== folderId);
+      const restoreIndex = Math.min(
+        Math.max(0, Number(trashEntry.originalFolderOrderIndex || 0)),
+        folderOrder.length
+      );
+      folderOrder.splice(restoreIndex, 0, folderId);
+      nextState.folderOrder = folderOrder;
+      delete nextState.deletedFolderTombstones[folderId];
+      nextState.records[folderId].forEach((record) => {
+        delete nextState.deletedRecordTombstones[record.id];
+      });
+      delete nextState.trashEntries[trashEntryId];
+      break;
+    }
+
+    case OPERATION_TYPES.TRASH_PURGE: {
+      const trashEntryId = normalizeId(payload.trashEntryId || payload.id);
+      const trashEntry = nextState.trashEntries[trashEntryId];
+      if (!trashEntry) return normalized;
+      if (payload.expectedGeneration &&
+        Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) return normalized;
+      delete nextState.trashEntries[trashEntryId];
+      break;
+    }
+
+    case OPERATION_TYPES.TRASH_RESTORE_BATCH: {
+      const batchId = normalizeId(payload.batchId);
+      if (!batchId) return normalized;
+      let restoredState = nextState;
+      Object.values(nextState.trashEntries)
+        .filter((entry) => entry.batchId === batchId)
+        .sort((left, right) => left.kind === 'folder' ? -1 : right.kind === 'folder' ? 1 : 0)
+        .forEach((entry, index) => {
+          restoredState = applyOperation(restoredState, {
+            ...operation,
+            id: `${operation.id || 'trash.restoreBatch'}:${index}`,
+            type: entry.kind === 'folder'
+              ? OPERATION_TYPES.FOLDER_RESTORE
+              : OPERATION_TYPES.RECORD_RESTORE,
+            payload: {trashEntryId: entry.id, expectedGeneration: entry.lifecycleGeneration}
+          });
+        });
+      return restoredState;
+    }
+
+    case OPERATION_TYPES.TRASH_PURGE_BATCH: {
+      const batchId = normalizeId(payload.batchId);
+      if (!batchId) return normalized;
+      Object.values(nextState.trashEntries).forEach((entry) => {
+        if (entry.batchId === batchId) delete nextState.trashEntries[entry.id];
+      });
+      break;
+    }
+
+    case OPERATION_TYPES.TRASH_EMPTY: {
+      const cutoffAt = toFiniteTimestamp(payload.cutoffAt) || operationTime;
+      Object.values(nextState.trashEntries).forEach((entry) => {
+        if (toFiniteTimestamp(entry.deletedAt) <= cutoffAt) delete nextState.trashEntries[entry.id];
+      });
       break;
     }
 
@@ -808,6 +1068,7 @@ export const mergeLocalRemote = ({
     remote.deletedFolderTombstones,
     local.deletedFolderTombstones
   );
+  const trashEntries = mergeTrashEntries(remote.trashEntries, local.trashEntries);
   const folders = mergeFolders(remote.folders, local.folders, deletedFolderTombstones);
   const folderIds = new Set(ensureFolders(folders).map((folder) => folder.id));
 
@@ -821,6 +1082,7 @@ export const mergeLocalRemote = ({
     settings: { ...remote.settings, ...local.settings },
     deletedRecordTombstones,
     deletedFolderTombstones,
+    trashEntries,
     rtlSyncMeta: {
       ...remote.rtlSyncMeta,
       ...local.rtlSyncMeta,
@@ -973,6 +1235,7 @@ export const buildLocalStateFromStorage = (data = {}, options = {}) => normalize
   rtlSyncMeta: data.rtlSyncMeta || {},
   deletedRecordTombstones: data.deletedRecordTombstones || {},
   deletedFolderTombstones: data.deletedFolderTombstones || {},
+  trashEntries: data.trashEntries || {},
   lastModified: data.lastModified || data.updatedAt || 0
 });
 
@@ -991,6 +1254,7 @@ export const buildStoragePatchFromState = (state = {}, options = {}) => {
     rtlSyncMeta: normalized.rtlSyncMeta,
     deletedRecordTombstones: normalized.deletedRecordTombstones,
     deletedFolderTombstones: normalized.deletedFolderTombstones,
+    trashEntries: normalized.trashEntries,
     lastModified: normalized.lastModified || resolveNow(options.now)
   };
 
@@ -1019,6 +1283,7 @@ export const buildFirestoreV1UserPatch = (state = {}, options = {}) => {
     },
     deletedRecordTombstones: normalized.deletedRecordTombstones || {},
     deletedFolderTombstones: normalized.deletedFolderTombstones || {},
+    trashEntries: normalized.trashEntries || {},
     lastModified: normalized.lastModified || resolveNow(options.now)
   };
 };
@@ -1030,6 +1295,8 @@ export const buildFirestoreV2LogicalPaths = (userId = '{uid}') => {
     root,
     records: `${root}/records`,
     folders: `${root}/folders`,
+    trash: `${root}/trash`,
+    lifecycleTombstones: `${root}/lifecycleTombstones`,
     settings: root,
     ops: `${root}/ops`
   };
@@ -1223,6 +1490,18 @@ const cleanV2OperationDocument = (operation = {}, now) => {
   };
 };
 
+const cleanV2TrashDocument = (entry = {}, now) => {
+  const normalized = normalizeTrashEntries({[entry?.id || '']: entry});
+  const trashEntry = Object.values(normalized)[0];
+  if (!trashEntry) return null;
+  return {
+    ...trashEntry,
+    deletedAt: trashEntry.deletedAt || now,
+    purgeAt: trashEntry.purgeAt || now + RTL_TRASH_RETENTION_MS,
+    schemaVersion: 2
+  };
+};
+
 export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) => {
   const normalized = normalizeState(state || {});
   const now = resolveNow(options.now);
@@ -1252,6 +1531,12 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     if (operationDoc) ops[operationDoc.id] = operationDoc;
   });
 
+  const trash = {};
+  Object.values(normalized.trashEntries || {}).forEach((entry) => {
+    const trashDocument = cleanV2TrashDocument(entry, now);
+    if (trashDocument) trash[trashDocument.id] = trashDocument;
+  });
+
   const root = {
     id: FIRESTORE_V2_SETTINGS_DOC_ID,
     schemaVersion: 2,
@@ -1274,6 +1559,7 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     root,
     records,
     folders,
+    trash,
     ops
   };
 };
@@ -1365,7 +1651,12 @@ export const buildFirestoreV2DocumentChangeSet = (
     nextDocuments?.ops,
     allowDeletes
   );
-  const hasCollectionChanges = [records, folders, ops].some((changeSet) => (
+  const trash = buildFirestoreV2CollectionChangeSet(
+    previousDocuments?.trash,
+    nextDocuments?.trash,
+    allowDeletes
+  );
+  const hasCollectionChanges = [records, folders, trash, ops].some((changeSet) => (
     Object.keys(changeSet.upserts).length > 0 || changeSet.deleteIds.length > 0
   ));
 
@@ -1374,6 +1665,7 @@ export const buildFirestoreV2DocumentChangeSet = (
     root: { upsert: rootUpsert },
     records,
     folders,
+    trash,
     ops
   };
 };
@@ -1418,6 +1710,25 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
     })
     .filter(Boolean);
 
+  const trashEntries = normalizeTrashEntries(Object.fromEntries(
+    mapValuesArray(documents?.trash)
+      .map((entry) => [entry?.id, removeV2Metadata(entry)])
+      .filter(([id]) => normalizeId(id))
+  ));
+  Object.values(trashEntries).forEach((entry) => {
+    const parentEntryId = normalizeId(entry.parentEntryId);
+    const parent = parentEntryId ? trashEntries[parentEntryId] : null;
+    const record = entry.hidden === true ? entry.payload?.record : null;
+    if (!parent || parent.kind !== 'folder' || !record) return;
+    const existingRecords = toArray(parent.payload?.records);
+    if (existingRecords.some((candidate) => getRecordId(candidate) === getRecordId(record))) return;
+    parent.payload = {
+      ...(parent.payload || {}),
+      records: [...existingRecords, record]
+    };
+    parent.recordCount = Math.max(Number(parent.recordCount || 0), parent.payload.records.length);
+  });
+
   const state = normalizeState({
     folders,
     records: reorderV2RecordsByFolderRecordOrder(records, recordOrderByFolder),
@@ -1428,6 +1739,7 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
     rtlSyncMeta: rootDoc.rtlSyncMeta || {},
     deletedRecordTombstones: rootDoc.deletedRecordTombstones || {},
     deletedFolderTombstones: rootDoc.deletedFolderTombstones || {},
+    trashEntries,
     lastModified: rootDoc.lastModified || 0
   });
 
@@ -1616,6 +1928,7 @@ const buildSyncStateInput = (data = {}, operationTime, options = {}) => ({
   rtlSyncMeta: data?.rtlSyncMeta || {},
   deletedRecordTombstones: data?.deletedRecordTombstones || {},
   deletedFolderTombstones: data?.deletedFolderTombstones || {},
+  trashEntries: data?.trashEntries || {},
   lastModified: operationTime
 });
 
@@ -2207,7 +2520,13 @@ export const createSyncEngine = ({
 
 const RTL_SYNC_CLIENT_APPS = new Set(['extension', 'flowmoor']);
 const RTL_SUPPORTED_OPERATION_TYPES = new Set(Object.values(OPERATION_TYPES));
-const RTL_BULK_OPERATION_TYPES = new Set([OPERATION_TYPES.FOLDER_DELETE]);
+const RTL_BULK_OPERATION_TYPES = new Set([
+  OPERATION_TYPES.FOLDER_DELETE,
+  OPERATION_TYPES.FOLDER_RESTORE,
+  OPERATION_TYPES.TRASH_RESTORE_BATCH,
+  OPERATION_TYPES.TRASH_PURGE_BATCH,
+  OPERATION_TYPES.TRASH_EMPTY
+]);
 const RTL_PROTECTED_FOLDER_IDS = new Set(['all', DEFAULT_FOLDER_ID]);
 
 const rtlByteLength = (value) => new TextEncoder().encode(String(value)).byteLength;
@@ -2217,10 +2536,14 @@ const rtlOperationRecordId = (operation = {}) => normalizeId(
 const rtlOperationFolderId = (operation = {}) => normalizeId(
   operation?.payload?.folderId || operation?.payload?.id || operation?.payload?.folder?.id
 );
+const rtlOperationTrashEntryId = (operation = {}) => normalizeId(
+  operation?.payload?.trashEntryId || operation?.payload?.id
+);
 const rtlCloneDocuments = (documents = {}) => ({
   root: clone(documents.root || null),
   records: clone(documents.records || {}),
   folders: clone(documents.folders || {}),
+  trash: clone(documents.trash || {}),
   ops: {}
 });
 const rtlMergeOrder = (...orders) => normalizeOrder(orders.flatMap((order) => toArray(order)));
@@ -2276,6 +2599,9 @@ const rtlValidateOperationPayload = (operation, index, errors) => {
     case OPERATION_TYPES.RECORD_DELETE:
       if (!recordId) errors.push(`operation_${index}_missing_record_id`);
       break;
+    case OPERATION_TYPES.RECORD_RESTORE:
+      if (!rtlOperationTrashEntryId(operation)) errors.push(`operation_${index}_missing_trash_entry_id`);
+      break;
     case OPERATION_TYPES.RECORD_REORDER:
       if (!folderId) errors.push(`operation_${index}_missing_folder_id`);
       rtlValidateIdList(payload.recordIds, index, 'record_ids', errors);
@@ -2292,6 +2618,17 @@ const rtlValidateOperationPayload = (operation, index, errors) => {
     case OPERATION_TYPES.FOLDER_DELETE:
       if (!folderId) errors.push(`operation_${index}_missing_folder_id`);
       break;
+    case OPERATION_TYPES.FOLDER_RESTORE:
+    case OPERATION_TYPES.TRASH_PURGE:
+      if (!rtlOperationTrashEntryId(operation)) errors.push(`operation_${index}_missing_trash_entry_id`);
+      break;
+    case OPERATION_TYPES.TRASH_RESTORE_BATCH:
+    case OPERATION_TYPES.TRASH_PURGE_BATCH:
+      if (!normalizeId(payload.batchId)) errors.push(`operation_${index}_missing_batch_id`);
+      break;
+    case OPERATION_TYPES.TRASH_EMPTY:
+      if (!toFiniteTimestamp(payload.cutoffAt)) errors.push(`operation_${index}_missing_cutoff_at`);
+      break;
     case OPERATION_TYPES.FOLDER_REORDER:
       rtlValidateIdList(payload.folderOrder || payload.order, index, 'folder_order', errors);
       break;
@@ -2390,6 +2727,7 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
   const recordIds = new Set();
   const folderIds = new Set();
   const folderDeleteIds = new Set();
+  const trashEntryIds = new Set();
   toArray(operations).filter(Boolean).forEach((operation) => {
     const payload = operation.payload || {};
     switch (operation.type) {
@@ -2408,6 +2746,12 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
         if (recordId) recordIds.add(recordId);
         break;
       }
+      case OPERATION_TYPES.RECORD_RESTORE:
+      case OPERATION_TYPES.TRASH_PURGE: {
+        const trashEntryId = rtlOperationTrashEntryId(operation);
+        if (trashEntryId) trashEntryIds.add(trashEntryId);
+        break;
+      }
       case OPERATION_TYPES.RECORD_REORDER:
         folderIds.add(safeFolderId(payload.folderId));
         break;
@@ -2425,14 +2769,15 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
         break;
     }
   });
-  return {recordIds, folderIds, folderDeleteIds};
+  return {recordIds, folderIds, folderDeleteIds, trashEntryIds};
 };
 
 export const extendFirestoreV2OperationReadPlanWithRecords = (readPlan, records = {}) => {
   const next = {
     recordIds: new Set(readPlan?.recordIds || []),
     folderIds: new Set(readPlan?.folderIds || []),
-    folderDeleteIds: new Set(readPlan?.folderDeleteIds || [])
+    folderDeleteIds: new Set(readPlan?.folderDeleteIds || []),
+    trashEntryIds: new Set(readPlan?.trashEntryIds || [])
   };
   Object.values(records || {}).forEach((record) => {
     next.folderIds.add(safeFolderId(record?.folderId));
@@ -2440,9 +2785,23 @@ export const extendFirestoreV2OperationReadPlanWithRecords = (readPlan, records
   return next;
 };
 
-const rtlApplyOperationToPartialDocuments = ({root, records, folders, operation, now}) => {
+export const extendFirestoreV2OperationReadPlanWithTrash = (readPlan, trashEntries = {}) => {
+  const next = {
+    recordIds: new Set(readPlan?.recordIds || []),
+    folderIds: new Set(readPlan?.folderIds || []),
+    folderDeleteIds: new Set(readPlan?.folderDeleteIds || []),
+    trashEntryIds: new Set(readPlan?.trashEntryIds || [])
+  };
+  Object.values(trashEntries || {}).forEach((entry) => {
+    if (entry?.kind === 'record') next.folderIds.add(safeFolderId(entry.originalFolderId));
+  });
+  next.folderIds.add(DEFAULT_FOLDER_ID);
+  return next;
+};
+
+const rtlApplyOperationToPartialDocuments = ({root, records, folders, trash, operation, now}) => {
   const {state} = buildStateFromFirestoreV2Documents({
-    root: root || {}, records: records || {}, folders: folders || {}, ops: {}
+    root: root || {}, records: records || {}, folders: folders || {}, trash: trash || {}, ops: {}
   });
   const nextState = applyRecordTimeLabelOperation(state, operation);
   return {
@@ -2454,12 +2813,7 @@ const rtlApplyOperationToPartialDocuments = ({root, records, folders, operation,
 const rtlCanRestoreLocalFolder = (root, folder) => {
   if (!folder?.id) return false;
   const tombstone = root?.deletedFolderTombstones?.[folder.id];
-  if (!tombstone) return true;
-  const folderTime = toFiniteTimestamp(folder.updatedAt || folder.createdAt || folder.lastModified);
-  const deletedAt = toFiniteTimestamp(
-    tombstone.deletedAt || tombstone.updatedAt || tombstone.createdAt
-  );
-  return Boolean(folderTime) && Boolean(deletedAt) && folderTime > deletedAt;
+  return !tombstone;
 };
 
 const rtlBuildLocalFolderDocument = (folder, now) => {
@@ -2526,21 +2880,23 @@ export const planFirestoreV2OperationChanges = ({
         });
         const recordDocument = applied.documents.records[recordId];
         if (!recordDocument) { reason = 'blocked_by_tombstone'; break; }
-        rtlSetRoot(nextDocuments.root, applied.documents.root);
-        nextDocuments.records[recordId] = recordDocument;
+        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';
-          delete nextDocuments.records[recordId];
           break;
         }
         targetFolder.recordOrder = rtlMergeOrder([recordId], targetFolder.recordOrder);
+        rtlSetRoot(nextDocuments.root, candidateRoot);
+        nextDocuments.folders = candidateFolders;
+        nextDocuments.records[recordId] = recordDocument;
         changed = true;
         break;
       }
@@ -2614,6 +2970,9 @@ export const planFirestoreV2OperationChanges = ({
         const sourceFolderId = safeFolderId(nextDocuments.records[recordId]?.folderId);
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         rtlSetRoot(nextDocuments.root, applied.documents.root);
+        const trashEntryId = normalizeId(payload.trashEntryId) || `record:${recordId}`;
+        const trashDocument = applied.documents.trash?.[trashEntryId];
+        if (trashDocument) nextDocuments.trash[trashEntryId] = trashDocument;
         delete nextDocuments.records[recordId];
         if (nextDocuments.folders[sourceFolderId]) {
           nextDocuments.folders[sourceFolderId].recordOrder = rtlMergeOrder(
@@ -2623,6 +2982,50 @@ export const planFirestoreV2OperationChanges = ({
         changed = true;
         break;
       }
+      case OPERATION_TYPES.RECORD_RESTORE: {
+        const trashEntryId = rtlOperationTrashEntryId(operation);
+        const trashEntry = nextDocuments.trash[trashEntryId];
+        if (!trashEntry) { reason = 'trash_entry_not_found'; break; }
+        if (toFiniteTimestamp(trashEntry.purgeAt) <= operationNow) {
+          reason = 'trash_entry_expired';
+          break;
+        }
+        const restoredRecordId = normalizeId(trashEntry.entityId);
+        if (!restoredRecordId || nextDocuments.records[restoredRecordId]) {
+          reason = restoredRecordId ? 'already_exists' : 'missing_record_id';
+          break;
+        }
+        applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
+        const restoredRecord = applied.documents.records[restoredRecordId];
+        if (!restoredRecord) { reason = 'restore_conflict'; break; }
+        const targetFolderId = safeFolderId(restoredRecord.folderId || trashEntry.originalFolderId);
+        const targetFolder = nextDocuments.folders[targetFolderId] ||
+          nextDocuments.folders[DEFAULT_FOLDER_ID];
+        if (!targetFolder) { reason = 'folder_not_found'; break; }
+        rtlSetRoot(nextDocuments.root, applied.documents.root);
+        nextDocuments.records[restoredRecordId] = restoredRecord;
+        delete nextDocuments.trash[trashEntryId];
+        targetFolder.recordOrder = rtlMergeOrder(
+          targetFolder.recordOrder.slice(0, Number(trashEntry.originalRecordIndex || 0)),
+          [restoredRecordId],
+          targetFolder.recordOrder.slice(Number(trashEntry.originalRecordIndex || 0))
+        );
+        changed = true;
+        break;
+      }
+      case OPERATION_TYPES.TRASH_PURGE: {
+        const trashEntryId = rtlOperationTrashEntryId(operation);
+        const trashEntry = nextDocuments.trash[trashEntryId];
+        if (!trashEntry) { reason = 'trash_entry_not_found'; break; }
+        if (payload.expectedGeneration &&
+          Number(payload.expectedGeneration) !== Number(trashEntry.lifecycleGeneration)) {
+          reason = 'lifecycle_conflict';
+          break;
+        }
+        delete nextDocuments.trash[trashEntryId];
+        changed = true;
+        break;
+      }
       case OPERATION_TYPES.FOLDER_CREATE:
       case OPERATION_TYPES.FOLDER_UPDATE: {
         if (!folderId) { reason = 'missing_folder_id'; break; }
@@ -2643,6 +3046,10 @@ export const planFirestoreV2OperationChanges = ({
         break;
       }
       case OPERATION_TYPES.FOLDER_DELETE:
+      case OPERATION_TYPES.FOLDER_RESTORE:
+      case OPERATION_TYPES.TRASH_RESTORE_BATCH:
+      case OPERATION_TYPES.TRASH_PURGE_BATCH:
+      case OPERATION_TYPES.TRASH_EMPTY:
         reason = 'bulk_required';
         break;
       case OPERATION_TYPES.FOLDER_REORDER:
@@ -2687,7 +3094,7 @@ export const planFirestoreV2OperationChanges = ({
 
   if (changed) {
     const {state} = buildStateFromFirestoreV2Documents({
-      root: nextDocuments.root, records: {}, folders: {}, ops: {}
+      root: nextDocuments.root, records: {}, folders: {}, trash: {}, ops: {}
     });
     nextDocuments.root = buildFirestoreV2DocumentsFromState(state, {
       now,
@@ -2710,7 +3117,7 @@ export const planFirestoreV2OperationChanges = ({
  * Counts all billable writes before a transaction reserves quota.
  */
 export const estimateFirestoreV2WriteUnits = (changes = {}, overhead = 3) => {
-  const collectionWrites = ['records', 'folders', 'ops'].reduce((count, key) => (
+  const collectionWrites = ['records', 'folders', 'trash', 'ops'].reduce((count, key) => (
     count + Object.keys(changes?.[key]?.upserts || {}).length +
       toArray(changes?.[key]?.deleteIds).length
   ), 0);
@@ -2751,6 +3158,7 @@ export const buildOperationsFromSnapshotDiff = ({
   const previousFolders = new Map(previous.folders.map((folder) => [folder.id, folder]));
   const nextFolders = new Map(next.folders.map((folder) => [folder.id, folder]));
   const drafts = [];
+  const bulkDrafts = [];
 
   nextFolders.forEach((folder, folderId) => {
     if (RTL_PROTECTED_FOLDER_IDS.has(folderId)) return;
@@ -2787,7 +3195,10 @@ export const buildOperationsFromSnapshotDiff = ({
 
   previousFolders.forEach((folder, folderId) => {
     if (!RTL_PROTECTED_FOLDER_IDS.has(folderId) && !nextFolders.has(folderId)) {
-      drafts.push({type: OPERATION_TYPES.FOLDER_DELETE, payload: {folderId}});
+      bulkDrafts.push({
+        type: OPERATION_TYPES.FOLDER_DELETE,
+        payload: {folderId, deletedAt: now}
+      });
     }
   });
 
@@ -2812,6 +3223,11 @@ export const buildOperationsFromSnapshotDiff = ({
     createdAt: now + index,
     ...draft
   }));
+  const bulkOperations = bulkDrafts.map((draft, index) => ({
+    id: `${operationIdPrefix}:bulk:${String(index).padStart(6, '0')}`,
+    createdAt: now + operations.length + index,
+    ...draft
+  }));
   const boundedBatchSize = Math.max(1, Math.min(
     RTL_MAX_OPERATIONS_PER_REQUEST,
     Number.isSafeInteger(batchSize) ? batchSize : RTL_MAX_OPERATIONS_PER_REQUEST
@@ -2826,7 +3242,14 @@ export const buildOperationsFromSnapshotDiff = ({
   const changes = buildFirestoreV2DocumentChangeSet(previousDocuments, nextDocuments, {
     allowDeletes: true
   });
-  return {operations, batches, changes, previousDocuments, nextDocuments};
+  return {
+    operations,
+    batches,
+    bulkOperations,
+    changes,
+    previousDocuments,
+    nextDocuments
+  };
 };
 
 export default {
@@ -2835,11 +3258,13 @@ export default {
   RTL_MAX_OPERATIONS_PER_REQUEST,
   RTL_MAX_REQUEST_BYTES,
   RTL_MAX_TARGET_WRITES,
+  RTL_TRASH_RETENTION_MS,
   OPERATION_TYPES,
   RECORD_TIMELABEL_SYNC_MODES,
   RECORD_TIMELABEL_CLOUD_SCHEMAS,
   FIRESTORE_V2_SETTINGS_DOC_ID,
   normalizeState,
+  getActiveTrashEntries,
   hasMeaningfulRecordTimeLabelCloudState,
   buildRecordTimeLabelContentFingerprint,
   buildMigratedRecordTimeLabelV2State,
@@ -2862,6 +3287,7 @@ export default {
   validateRecordTimeLabelOperationBatch,
   buildFirestoreV2OperationReadPlan,
   extendFirestoreV2OperationReadPlanWithRecords,
+  extendFirestoreV2OperationReadPlanWithTrash,
   planFirestoreV2OperationChanges,
   estimateFirestoreV2WriteUnits,
   buildOperationsFromSnapshotDiff,