@recordtimelabel/core 0.3.0 → 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.3.0"
+"@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.
@@ -83,6 +83,12 @@ 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.
+
 ## 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.3.0",
+  "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,7 +5,7 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.3.0';
+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;
@@ -241,6 +241,66 @@ const mergeTrashEntries = (remoteEntries = {}, localEntries = {}) => {
   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,
@@ -1060,15 +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 trashEntries = mergeTrashEntries(remote.trashEntries, local.trashEntries);
+  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));