@recordtimelabel/core 0.3.0 → 0.3.2

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.2"
 ```
 
 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,17 @@ 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 and newer, and restore
+operations are what bump the generation. When generations tie — an active copy written outside the
+delete/restore path — the active copy's own timestamp breaks the tie against `deletedAt`. A stale
+snapshot on either side therefore cannot re-delete an entity that was already restored.
+
+Consumers must not reimplement this reconciliation in an app-level wrapper. In particular, never
+clear a local tombstone just because the remote snapshot still carries the entity as active: that
+is presence-based inference, the same anti-pattern as the five-minute heuristic above, and it is not
+order-independent, so two clients using different rules will not converge on shared cloud data.
+
 ## Firestore v2 Gateway Contract
 
 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.2",
   "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.2';
 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,82 @@ const mergeTrashEntries = (remoteEntries = {}, localEntries = {}) => {
   return merged;
 };
 
+const collectActiveLifecycleStates = (...states) => {
+  const records = new Map();
+  const folders = new Map();
+  const track = (target, id, entity, time) => {
+    if (!id) return;
+    const generation = Number(entity?.lifecycleGeneration || 0);
+    const current = target.get(id);
+    if (current && (current.generation > generation ||
+      (current.generation === generation && current.time >= time))) return;
+    target.set(id, { generation, time });
+  };
+  states.forEach((state) => {
+    Object.entries(state?.records || {}).forEach(([folderId, folderRecords]) => {
+      if (VIRTUAL_FOLDER_IDS.has(normalizeId(folderId))) return;
+      toArray(folderRecords).forEach((record) => (
+        track(records, getRecordId(record), record, getRecordTime(record))
+      ));
+    });
+    toArray(state?.folders).forEach((folder) => (
+      track(folders, normalizeId(folder?.id), folder, getFolderTime(folder))
+    ));
+  });
+  return { records, folders };
+};
+
+/**
+ * A tombstone or trash entry only stays valid while it describes the newest lifecycle event for
+ * its entity. Once either side carries that entity as active and newer, the deletion is stale and
+ * must be dropped, otherwise mergeTombstones' union lets a stale snapshot re-delete a record that
+ * was already restored.
+ *
+ * "Newer" is decided by lifecycleGeneration first — restore operations bump it, and generations
+ * default to 0 so legacy data never outranks a real tombstone. Generations only tie when an active
+ * copy was written outside the delete/restore path, and there the active copy's own timestamp
+ * breaks the tie. That tie-break also makes this consistent with mergeLocalRemote's local-record
+ * loop, which already intends a record newer than `deletedAt` to survive its tombstone.
+ */
+const dropSupersededLifecycleDeletions = ({
+  deletedRecordTombstones = {},
+  deletedFolderTombstones = {},
+  trashEntries = {},
+  activeGenerations
+}) => {
+  const isSuperseded = (target, id, deletion) => {
+    const active = target.get(normalizeId(id));
+    if (!active) return false;
+    const deletionGeneration = Number(deletion?.lifecycleGeneration || 0);
+    if (active.generation !== deletionGeneration) return active.generation > deletionGeneration;
+    return active.time > toFiniteTimestamp(deletion?.deletedAt);
+  };
+  const nextRecordTombstones = { ...deletedRecordTombstones };
+  Object.entries(nextRecordTombstones).forEach(([recordId, tombstone]) => {
+    if (isSuperseded(activeGenerations.records, recordId, tombstone)) {
+      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 +1136,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: collectActiveLifecycleStates(remote, local)
+  });
   const folders = mergeFolders(remote.folders, local.folders, deletedFolderTombstones);
   const folderIds = new Set(ensureFolders(folders).map((folder) => folder.id));