@recordtimelabel/core 0.2.1 → 0.3.1

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.1"
+"@recordtimelabel/core": "0.3.1"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -48,6 +48,7 @@ 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 })`（一般操作在 `batches`，`folder.delete` 在 `bulkOperations`）
@@ -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,9 +79,16 @@ 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.
 
+`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.
+
 ## Firestore v2 Gateway Contract
 
 The package exposes platform-neutral v2 document helpers so app adapters can share the same record/folder/settings/ops shape before wiring Firebase SDK or REST calls:
@@ -86,6 +96,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.1",
+  "version": "0.3.1",
   "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.1';
-export const RTL_SYNC_PROTOCOL_VERSION = 1;
+export const RECORD_TIMELABEL_CORE_VERSION = '0.3.1';
+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([
@@ -63,6 +70,14 @@ const clone = (value, seen = new WeakMap()) => {
 };
 
 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;
   }
@@ -168,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]) => {
@@ -179,6 +227,80 @@ 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 collectActiveLifecycleGenerations = (...states) => {
+  const records = new Map();
+  const folders = new Map();
+  const track = (target, id, entity) => {
+    if (!id) return;
+    const generation = Number(entity?.lifecycleGeneration || 0);
+    target.set(id, Math.max(generation, target.get(id) || 0));
+  };
+  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(state?.folders).forEach((folder) => track(folders, normalizeId(folder?.id), 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.
+ */
+const dropSupersededLifecycleDeletions = ({
+  deletedRecordTombstones = {},
+  deletedFolderTombstones = {},
+  trashEntries = {},
+  activeGenerations
+}) => {
+  const isSuperseded = (target, id, deletion) => (
+    (target.get(normalizeId(id)) || 0) > Number(deletion?.lifecycleGeneration || 0)
+  );
+  const nextRecordTombstones = { ...deletedRecordTombstones };
+  Object.entries(nextRecordTombstones).forEach(([recordId, tombstone]) => {
+    if (isSuperseded(activeGenerations.records, recordId, tombstone)) {
+      delete nextRecordTombstones[recordId];
+    }
+  });
+  const nextFolderTombstones = { ...deletedFolderTombstones };
+  Object.entries(nextFolderTombstones).forEach(([folderId, tombstone]) => {
+    if (isSuperseded(activeGenerations.folders, folderId, tombstone)) {
+      delete nextFolderTombstones[folderId];
+    }
+  });
+  const nextTrashEntries = { ...trashEntries };
+  Object.values(nextTrashEntries).forEach((entry) => {
+    const target = entry?.kind === 'folder' ? activeGenerations.folders : activeGenerations.records;
+    if (isSuperseded(target, entry?.entityId, entry)) {
+      delete nextTrashEntries[entry.id];
+    }
+  });
+  return {
+    deletedRecordTombstones: nextRecordTombstones,
+    deletedFolderTombstones: nextFolderTombstones,
+    trashEntries: nextTrashEntries
+  };
+};
+
 const resolveRecordFolderId = (folderId, record = {}) => {
   const candidates = [
     record.folderId,
@@ -256,13 +378,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] = [];
 
@@ -363,9 +481,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) {
@@ -401,9 +517,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 }),
@@ -423,6 +537,7 @@ export const normalizeState = (input = {}) => {
     },
     deletedRecordTombstones,
     deletedFolderTombstones,
+    trashEntries: normalizeTrashEntries(input.trashEntries),
     lastModified: toFiniteTimestamp(input.lastModified || input.updatedAt || input.lastUpdated)
   };
 };
@@ -445,6 +560,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;
@@ -460,7 +576,8 @@ export const buildRecordTimeLabelContentFingerprint = (input = {}) => {
     folderOrder: state.folderOrder,
     expandedGroups: state.expandedGroups,
     deletedRecordTombstones: state.deletedRecordTombstones,
-    deletedFolderTombstones: state.deletedFolderTombstones
+    deletedFolderTombstones: state.deletedFolderTombstones,
+    trashEntries: state.trashEntries
   });
 };
 
@@ -601,10 +718,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 = {
@@ -709,20 +823,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 || {}),
@@ -753,16 +932,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;
     }
 
@@ -811,14 +1120,22 @@ export const mergeLocalRemote = ({
 } = {}) => {
   const local = normalizeState(localState);
   const remote = normalizeState(remoteState);
-  const deletedRecordTombstones = mergeTombstones(
-    remote.deletedRecordTombstones,
-    local.deletedRecordTombstones
-  );
-  const deletedFolderTombstones = mergeTombstones(
-    remote.deletedFolderTombstones,
-    local.deletedFolderTombstones
-  );
+  const {
+    deletedRecordTombstones,
+    deletedFolderTombstones,
+    trashEntries
+  } = dropSupersededLifecycleDeletions({
+    deletedRecordTombstones: mergeTombstones(
+      remote.deletedRecordTombstones,
+      local.deletedRecordTombstones
+    ),
+    deletedFolderTombstones: mergeTombstones(
+      remote.deletedFolderTombstones,
+      local.deletedFolderTombstones
+    ),
+    trashEntries: mergeTrashEntries(remote.trashEntries, local.trashEntries),
+    activeGenerations: collectActiveLifecycleGenerations(remote, local)
+  });
   const folders = mergeFolders(remote.folders, local.folders, deletedFolderTombstones);
   const folderIds = new Set(ensureFolders(folders).map((folder) => folder.id));
 
@@ -832,6 +1149,7 @@ export const mergeLocalRemote = ({
     settings: { ...remote.settings, ...local.settings },
     deletedRecordTombstones,
     deletedFolderTombstones,
+    trashEntries,
     rtlSyncMeta: {
       ...remote.rtlSyncMeta,
       ...local.rtlSyncMeta,
@@ -984,6 +1302,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
 });
 
@@ -1002,6 +1321,7 @@ export const buildStoragePatchFromState = (state = {}, options = {}) => {
     rtlSyncMeta: normalized.rtlSyncMeta,
     deletedRecordTombstones: normalized.deletedRecordTombstones,
     deletedFolderTombstones: normalized.deletedFolderTombstones,
+    trashEntries: normalized.trashEntries,
     lastModified: normalized.lastModified || resolveNow(options.now)
   };
 
@@ -1030,6 +1350,7 @@ export const buildFirestoreV1UserPatch = (state = {}, options = {}) => {
     },
     deletedRecordTombstones: normalized.deletedRecordTombstones || {},
     deletedFolderTombstones: normalized.deletedFolderTombstones || {},
+    trashEntries: normalized.trashEntries || {},
     lastModified: normalized.lastModified || resolveNow(options.now)
   };
 };
@@ -1041,6 +1362,8 @@ export const buildFirestoreV2LogicalPaths = (userId = '{uid}') => {
     root,
     records: `${root}/records`,
     folders: `${root}/folders`,
+    trash: `${root}/trash`,
+    lifecycleTombstones: `${root}/lifecycleTombstones`,
     settings: root,
     ops: `${root}/ops`
   };
@@ -1234,6 +1557,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);
@@ -1263,6 +1598,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,
@@ -1285,6 +1626,7 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     root,
     records,
     folders,
+    trash,
     ops
   };
 };
@@ -1376,7 +1718,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
   ));
 
@@ -1385,6 +1732,7 @@ export const buildFirestoreV2DocumentChangeSet = (
     root: { upsert: rootUpsert },
     records,
     folders,
+    trash,
     ops
   };
 };
@@ -1429,6 +1777,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),
@@ -1439,6 +1806,7 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
     rtlSyncMeta: rootDoc.rtlSyncMeta || {},
     deletedRecordTombstones: rootDoc.deletedRecordTombstones || {},
     deletedFolderTombstones: rootDoc.deletedFolderTombstones || {},
+    trashEntries,
     lastModified: rootDoc.lastModified || 0
   });
 
@@ -1627,6 +1995,7 @@ const buildSyncStateInput = (data = {}, operationTime, options = {}) => ({
   rtlSyncMeta: data?.rtlSyncMeta || {},
   deletedRecordTombstones: data?.deletedRecordTombstones || {},
   deletedFolderTombstones: data?.deletedFolderTombstones || {},
+  trashEntries: data?.trashEntries || {},
   lastModified: operationTime
 });
 
@@ -2218,7 +2587,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;
@@ -2228,10 +2603,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)));
@@ -2287,6 +2666,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);
@@ -2303,6 +2685,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;
@@ -2401,6 +2794,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) {
@@ -2419,6 +2813,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;
@@ -2436,14 +2836,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));
@@ -2451,9 +2852,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 {
@@ -2465,12 +2880,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) => {
@@ -2627,6 +3037,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(
@@ -2636,6 +3049,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; }
@@ -2656,6 +3113,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:
@@ -2700,7 +3161,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,
@@ -2723,7 +3184,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);
@@ -2864,11 +3325,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,
@@ -2891,6 +3354,7 @@ export default {
   validateRecordTimeLabelOperationBatch,
   buildFirestoreV2OperationReadPlan,
   extendFirestoreV2OperationReadPlanWithRecords,
+  extendFirestoreV2OperationReadPlanWithTrash,
   planFirestoreV2OperationChanges,
   estimateFirestoreV2WriteUnits,
   buildOperationsFromSnapshotDiff,