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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.3.1",
+  "version": "0.3.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.1';
+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,30 +241,42 @@ const mergeTrashEntries = (remoteEntries = {}, localEntries = {}) => {
   return merged;
 };
 
-const collectActiveLifecycleGenerations = (...states) => {
+const collectActiveLifecycleStates = (...states) => {
   const records = new Map();
   const folders = new Map();
-  const track = (target, id, entity) => {
+  const track = (target, id, entity, time) => {
     if (!id) return;
     const generation = Number(entity?.lifecycleGeneration || 0);
-    target.set(id, Math.max(generation, target.get(id) || 0));
+    const current = target.get(id);
+    if (current && (current.generation > generation ||
+      (current.generation === generation && current.time >= time))) return;
+    target.set(id, { generation, time });
   };
   states.forEach((state) => {
     Object.entries(state?.records || {}).forEach(([folderId, folderRecords]) => {
       if (VIRTUAL_FOLDER_IDS.has(normalizeId(folderId))) return;
-      toArray(folderRecords).forEach((record) => track(records, getRecordId(record), record));
+      toArray(folderRecords).forEach((record) => (
+        track(records, getRecordId(record), record, getRecordTime(record))
+      ));
     });
-    toArray(state?.folders).forEach((folder) => track(folders, normalizeId(folder?.id), folder));
+    toArray(state?.folders).forEach((folder) => (
+      track(folders, normalizeId(folder?.id), folder, getFolderTime(folder))
+    ));
   });
   return { records, folders };
 };
 
 /**
  * A tombstone or trash entry only stays valid while it describes the newest lifecycle event for
- * its entity. Once either side carries that entity as active with a higher lifecycleGeneration —
- * which restore operations bump — the deletion is stale and must be dropped, otherwise
- * mergeTombstones' union lets a stale snapshot re-delete a record that was already restored.
- * Generations default to 0, so legacy data never outranks a real tombstone.
+ * its entity. Once either side carries that entity as active and newer, the deletion is stale and
+ * must be dropped, otherwise mergeTombstones' union lets a stale snapshot re-delete a record that
+ * was already restored.
+ *
+ * "Newer" is decided by lifecycleGeneration first — restore operations bump it, and generations
+ * default to 0 so legacy data never outranks a real tombstone. Generations only tie when an active
+ * copy was written outside the delete/restore path, and there the active copy's own timestamp
+ * breaks the tie. That tie-break also makes this consistent with mergeLocalRemote's local-record
+ * loop, which already intends a record newer than `deletedAt` to survive its tombstone.
  */
 const dropSupersededLifecycleDeletions = ({
   deletedRecordTombstones = {},
@@ -272,9 +284,13 @@ const dropSupersededLifecycleDeletions = ({
   trashEntries = {},
   activeGenerations
 }) => {
-  const isSuperseded = (target, id, deletion) => (
-    (target.get(normalizeId(id)) || 0) > Number(deletion?.lifecycleGeneration || 0)
-  );
+  const isSuperseded = (target, id, deletion) => {
+    const active = target.get(normalizeId(id));
+    if (!active) return false;
+    const deletionGeneration = Number(deletion?.lifecycleGeneration || 0);
+    if (active.generation !== deletionGeneration) return active.generation > deletionGeneration;
+    return active.time > toFiniteTimestamp(deletion?.deletedAt);
+  };
   const nextRecordTombstones = { ...deletedRecordTombstones };
   Object.entries(nextRecordTombstones).forEach(([recordId, tombstone]) => {
     if (isSuperseded(activeGenerations.records, recordId, tombstone)) {
@@ -1134,7 +1150,7 @@ export const mergeLocalRemote = ({
       local.deletedFolderTombstones
     ),
     trashEntries: mergeTrashEntries(remote.trashEntries, local.trashEntries),
-    activeGenerations: collectActiveLifecycleGenerations(remote, local)
+    activeGenerations: collectActiveLifecycleStates(remote, local)
   });
   const folders = mergeFolders(remote.folders, local.folders, deletedFolderTombstones);
   const folderIds = new Set(ensureFolders(folders).map((folder) => folder.id));