@recordtimelabel/core 0.3.2 → 0.4.0

package/src/index.js

@@ -1,3 +1,15 @@
+import {
+  RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  normalizeRecordTimeLabelEnvelopeResponse,
+  normalizeRecordTimeLabelOperationResults
+} from './protocol.js';
+
+export {
+  RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  normalizeRecordTimeLabelEnvelopeResponse,
+  normalizeRecordTimeLabelOperationResults
+} from './protocol.js';
+
 const DEFAULT_FOLDER_ID = 'uncategorized';
 const VIRTUAL_FOLDER_IDS = new Set(['all']);
 const REQUIRED_FOLDERS = [
@@ -5,7 +17,7 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.3.2';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.4.0';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
 export const RTL_MAX_REQUEST_BYTES = 256 * 1024;
@@ -52,6 +64,11 @@ export const RECORD_TIMELABEL_CLOUD_SCHEMAS = Object.freeze({
 
 export const FIRESTORE_V2_SETTINGS_DOC_ID = 'main';
 
+export const RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS = Object.freeze({
+  OWNER_MISMATCH: 'operation_owner_mismatch',
+  WORKSPACE_EPOCH_MISMATCH: 'operation_workspace_epoch_mismatch'
+});
+
 const toArray = (value) => (Array.isArray(value) ? value : []);
 const clone = (value, seen = new WeakMap()) => {
   if (value === undefined || value === null || typeof value !== 'object') return value;
@@ -220,7 +237,11 @@ const mergeTombstones = (left = {}, right = {}) => {
   const merged = { ...left };
   Object.entries(right).forEach(([id, tombstone]) => {
     const current = merged[id];
-    if (!current || toFiniteTimestamp(tombstone.deletedAt) >= toFiniteTimestamp(current.deletedAt)) {
+    const currentGeneration = Number(current?.lifecycleGeneration || 0);
+    const nextGeneration = Number(tombstone?.lifecycleGeneration || 0);
+    if (!current || nextGeneration > currentGeneration ||
+      (nextGeneration === currentGeneration &&
+        toFiniteTimestamp(tombstone.deletedAt) >= toFiniteTimestamp(current.deletedAt))) {
       merged[id] = { ...tombstone };
     }
   });
@@ -558,6 +579,49 @@ export const normalizeState = (input = {}) => {
   };
 };
 
+// `expandedGroups` is renderer navigation state. Keep the legacy normalizer
+// compatible for compat callers, but make the durable/core domain boundary
+// explicit so new engine and Firestore paths never carry it as cloud data.
+export const normalizeRecordTimeLabelDomainState = (input = {}) => {
+  const normalized = normalizeState(input);
+  const domain = {...normalized};
+  delete domain.expandedGroups;
+  return domain;
+};
+
+const expandedGroupsOperationType = 'expandedGroups.update';
+
+const expandedGroupsFromOperation = (operation = {}) => {
+  const payload = operation?.payload || {};
+  const values = [payload.expandedGroups, payload.groupIds, payload.order, payload.ids]
+    .find((candidate) => Array.isArray(candidate)) || [];
+  return normalizeOrder(values);
+};
+
+/**
+ * Migrate legacy view operations without inventing a cloud operation. Applying
+ * the operations in request order makes the helper idempotent after the
+ * returned operations are persisted and removed from the outbox.
+ */
+export const migrateRecordTimeLabelExpandedGroups = ({
+  pendingOperations = [],
+  currentView = []
+} = {}) => {
+  let expandedGroups = normalizeOrder(currentView);
+  const remainingOperations = [];
+  toArray(pendingOperations).forEach((operation) => {
+    if (operation?.type !== expandedGroupsOperationType) {
+      remainingOperations.push(clone(operation));
+      return;
+    }
+    expandedGroups = expandedGroupsFromOperation(operation);
+  });
+  return {
+    expandedGroups,
+    pendingOperations: remainingOperations
+  };
+};
+
 export const hasMeaningfulRecordTimeLabelCloudState = (input = {}, options = {}) => {
   const state = normalizeState(input || {});
   const defaultFolderIds = new Set(options.defaultFolderIds || ['all', 'uncategorized']);
@@ -578,8 +642,7 @@ export const hasMeaningfulRecordTimeLabelCloudState = (input = {}, options = {})
     Object.keys(state.deletedFolderTombstones || {}).length > 0 ||
     Object.keys(state.trashEntries || {}).length > 0 ||
     hasNonDefaultGroupOrder ||
-    state.folderOrder.length > 0 ||
-    state.expandedGroups.length > 0;
+    state.folderOrder.length > 0;
 };
 
 export const buildRecordTimeLabelContentFingerprint = (input = {}) => {
@@ -590,7 +653,6 @@ export const buildRecordTimeLabelContentFingerprint = (input = {}) => {
     settings: state.settings,
     groupOrder: state.groupOrder,
     folderOrder: state.folderOrder,
-    expandedGroups: state.expandedGroups,
     deletedRecordTombstones: state.deletedRecordTombstones,
     deletedFolderTombstones: state.deletedFolderTombstones,
     trashEntries: state.trashEntries
@@ -843,7 +905,8 @@ export const applyOperation = (state = {}, operation = {}) => {
       const recordSnapshot = payload.record && typeof payload.record === 'object'
         ? {...payload.record, id: recordId}
         : existingEntry?.record;
-      if (!recordSnapshot && nextState.trashEntries[`record:${recordId}`]) return normalized;
+      const trashEntryId = normalizeId(payload.trashEntryId) || `record:${recordId}`;
+      if (!recordSnapshot && nextState.trashEntries[trashEntryId]) return normalized;
       const deletedAt = toFiniteTimestamp(payload.deletedAt) || operationTime;
       const previousGeneration = Math.max(
         Number(recordSnapshot?.lifecycleGeneration || 0),
@@ -851,7 +914,6 @@ export const applyOperation = (state = {}, operation = {}) => {
       );
       const lifecycleGeneration = previousGeneration + 1;
       if (recordSnapshot) {
-        const trashEntryId = normalizeId(payload.trashEntryId) || `record:${recordId}`;
         nextState.trashEntries[trashEntryId] = {
           id: trashEntryId,
           kind: 'record',
@@ -967,6 +1029,8 @@ export const applyOperation = (state = {}, operation = {}) => {
           entityId: folderId,
           batchId: normalizeId(payload.batchId) || operation.id || trashEntryId,
           originalFolderOrderIndex: Math.max(0, nextState.folderOrder.indexOf(folderId)),
+          // -1 records "was not in groupOrder", so restore does not invent a placement.
+          originalGroupOrderIndex: nextState.groupOrder.indexOf(folderId),
           lifecycleGeneration,
           deletedAt,
           purgeAt: toFiniteTimestamp(payload.purgeAt) || deletedAt + RTL_TRASH_RETENTION_MS,
@@ -1036,6 +1100,15 @@ export const applyOperation = (state = {}, operation = {}) => {
       );
       folderOrder.splice(restoreIndex, 0, folderId);
       nextState.folderOrder = folderOrder;
+      // folder.delete strips the id from groupOrder too, so restore has to put it back.
+      const originalGroupOrderIndex = Number.isInteger(trashEntry.originalGroupOrderIndex)
+        ? trashEntry.originalGroupOrderIndex
+        : -1;
+      if (originalGroupOrderIndex >= 0) {
+        const groupOrder = nextState.groupOrder.filter((id) => id !== folderId);
+        groupOrder.splice(Math.min(originalGroupOrderIndex, groupOrder.length), 0, folderId);
+        nextState.groupOrder = groupOrder;
+      }
       delete nextState.deletedFolderTombstones[folderId];
       nextState.records[folderId].forEach((record) => {
         delete nextState.deletedRecordTombstones[record.id];
@@ -1100,8 +1173,9 @@ export const applyOperation = (state = {}, operation = {}) => {
       break;
 
     case OPERATION_TYPES.EXPANDED_GROUPS_UPDATE:
-      nextState.expandedGroups = normalizeOrder(payload.expandedGroups || payload.groupIds || payload.order || payload.ids);
-      break;
+      // Legacy view operations are migrated by the app adapter and are never
+      // part of the cloud/domain reducer.
+      return normalized;
 
     case OPERATION_TYPES.SETTINGS_UPDATE:
       nextState.settings = {
@@ -1585,6 +1659,29 @@ const cleanV2TrashDocument = (entry = {}, now) => {
   };
 };
 
+const buildV2LifecycleTombstoneDocuments = (
+  deletedRecordTombstones = {},
+  deletedFolderTombstones = {}
+) => {
+  const documents = {};
+  const append = (kind, tombstones) => {
+    Object.entries(normalizeTombstones(tombstones)).forEach(([entityId, tombstone]) => {
+      const id = `${kind}:${entityId}`;
+      documents[encodeURIComponent(id)] = {
+        id,
+        kind,
+        entityId,
+        lifecycleGeneration: Math.max(1, Number(tombstone.lifecycleGeneration || 1)),
+        deletedAt: toFiniteTimestamp(tombstone.deletedAt),
+        schemaVersion: 2
+      };
+    });
+  };
+  append('record', deletedRecordTombstones);
+  append('folder', deletedFolderTombstones);
+  return documents;
+};
+
 export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) => {
   const normalized = normalizeState(state || {});
   const now = resolveNow(options.now);
@@ -1620,13 +1717,17 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     if (trashDocument) trash[trashDocument.id] = trashDocument;
   });
 
+  const lifecycleTombstones = buildV2LifecycleTombstoneDocuments(
+    normalized.deletedRecordTombstones,
+    normalized.deletedFolderTombstones
+  );
+
   const root = {
     id: FIRESTORE_V2_SETTINGS_DOC_ID,
     schemaVersion: 2,
     settings: normalized.settings || {},
     groupOrder: normalizeGroupOrderForOption(normalized.groupOrder, options.groupOrderNormalizer),
     folderOrder: normalized.folderOrder,
-    expandedGroups: normalized.expandedGroups,
     rtlSyncMeta: {
       ...(normalized.rtlSyncMeta || {}),
       schemaVersion: 2,
@@ -1643,6 +1744,7 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     records,
     folders,
     trash,
+    lifecycleTombstones,
     ops
   };
 };
@@ -1716,8 +1818,15 @@ export const buildFirestoreV2DocumentChangeSet = (
   const allowDeletes = options.allowDeletes === true;
   const previousRoot = previousDocuments?.root;
   const nextRoot = nextDocuments?.root;
-  const rootUpsert = nextRoot && !areFirestoreV2DocumentValuesEqual(previousRoot, nextRoot)
-    ? nextRoot
+  const rootForComparison = nextRoot ? {...nextRoot} : nextRoot;
+  if (rootForComparison && previousRoot &&
+      Object.prototype.hasOwnProperty.call(previousRoot, 'expandedGroups')) {
+    rootForComparison.expandedGroups = previousRoot.expandedGroups;
+  } else if (rootForComparison) {
+    delete rootForComparison.expandedGroups;
+  }
+  const rootUpsert = rootForComparison && !areFirestoreV2DocumentValuesEqual(previousRoot, rootForComparison)
+    ? rootForComparison
     : null;
   const records = buildFirestoreV2CollectionChangeSet(
     previousDocuments?.records,
@@ -1739,7 +1848,12 @@ export const buildFirestoreV2DocumentChangeSet = (
     nextDocuments?.trash,
     allowDeletes
   );
-  const hasCollectionChanges = [records, folders, trash, ops].some((changeSet) => (
+  const lifecycleTombstones = buildFirestoreV2CollectionChangeSet(
+    previousDocuments?.lifecycleTombstones,
+    nextDocuments?.lifecycleTombstones,
+    allowDeletes
+  );
+  const hasCollectionChanges = [records, folders, trash, lifecycleTombstones, ops].some((changeSet) => (
     Object.keys(changeSet.upserts).length > 0 || changeSet.deleteIds.length > 0
   ));
 
@@ -1749,6 +1863,7 @@ export const buildFirestoreV2DocumentChangeSet = (
     records,
     folders,
     trash,
+    lifecycleTombstones,
     ops
   };
 };
@@ -1758,11 +1873,54 @@ const removeV2Metadata = (data = {}) => {
   return rest;
 };
 
+/**
+ * lifecycleTombstones 子集合的文件形狀是 { id: 'record:abc', kind, entityId, lifecycleGeneration,
+ * deletedAt }，拆成 record / folder 兩張以 entityId 為鍵的表，好跟 root 上的舊資料合併。
+ */
+const splitLifecycleTombstoneDocuments = (value) => {
+  const records = {};
+  const folders = {};
+  mapValuesArray(value).forEach((entry) => {
+    const entityId = normalizeId(entry?.entityId);
+    const kind = normalizeId(entry?.kind);
+    const target = kind === 'folder' ? folders : kind === 'record' ? records : null;
+    if (!entityId || !target) return;
+    target[entityId] = {
+      id: entityId,
+      lifecycleGeneration: Math.max(1, Number(entry.lifecycleGeneration || 1)),
+      deletedAt: toFiniteTimestamp(entry.deletedAt)
+    };
+  });
+  return { records, folders };
+};
+
+/**
+ * root 的 tombstone 表已停止成長，但既有帳號上仍留著歷史資料，因此兩邊都要讀。同一個 id 同時出現時
+ * 以世代優先、時間次之，跟 dropSupersededLifecycleDeletions 的判準一致。
+ */
+const mergeLifecycleTombstoneSources = (legacy = {}, subcollection = {}) => {
+  const merged = normalizeTombstones(legacy);
+  Object.entries(normalizeTombstones(subcollection)).forEach(([id, tombstone]) => {
+    const current = merged[id];
+    const currentGeneration = Number(current?.lifecycleGeneration || 0);
+    const nextGeneration = Number(tombstone.lifecycleGeneration || 0);
+    if (!current || nextGeneration > currentGeneration ||
+      (nextGeneration === currentGeneration &&
+        toFiniteTimestamp(tombstone.deletedAt) >= toFiniteTimestamp(current.deletedAt))) {
+      merged[id] = tombstone;
+    }
+  });
+  return merged;
+};
+
 export const buildStateFromFirestoreV2Documents = (documents = {}, options = {}) => {
   const rootDoc = documents?.root ||
     documents?.settings?.[FIRESTORE_V2_SETTINGS_DOC_ID] ||
     documents?.settings ||
     {};
+  const lifecycleTombstones = splitLifecycleTombstoneDocuments(
+    documents?.lifecycleTombstones
+  );
   const records = {};
   mapValuesArray(documents?.records).forEach((recordDoc) => {
     const recordId = normalizeId(recordDoc?.id);
@@ -1818,10 +1976,15 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
     settings: rootDoc.settings || {},
     groupOrder: normalizeGroupOrderForOption(rootDoc.groupOrder, options.groupOrderNormalizer),
     folderOrder: rootDoc.folderOrder || [],
-    expandedGroups: rootDoc.expandedGroups || [],
     rtlSyncMeta: rootDoc.rtlSyncMeta || {},
-    deletedRecordTombstones: rootDoc.deletedRecordTombstones || {},
-    deletedFolderTombstones: rootDoc.deletedFolderTombstones || {},
+    deletedRecordTombstones: mergeLifecycleTombstoneSources(
+      rootDoc.deletedRecordTombstones,
+      lifecycleTombstones.records
+    ),
+    deletedFolderTombstones: mergeLifecycleTombstoneSources(
+      rootDoc.deletedFolderTombstones,
+      lifecycleTombstones.folders
+    ),
     trashEntries,
     lastModified: rootDoc.lastModified || 0
   });
@@ -2144,7 +2307,7 @@ export const flushPendingOperations = async ({
   }
 
   const syncTime = resolveNow(now);
-  const storageData = await storageAdapter.load(storageKeys);
+  const storageData = (await storageAdapter.load(storageKeys)) || {};
   const latestPendingOps = toArray(storageData.pendingOps);
   const requestedIds = new Set(requestedOperations.map((operation) => operation?.id).filter(Boolean));
   const pendingOpsForPayload = latestPendingOps.filter((operation) => requestedIds.has(operation?.id));
@@ -2439,6 +2602,1037 @@ export const createRecordTimeLabelController = ({
   return controller;
 };
 
+/*
+ * Durable workspace engine
+ *
+ * The v1 engine above deliberately keeps its old storage/cloud contract.  The
+ * engine below is the platform-neutral contract used by newer adapters.  It
+ * stores a remote baseline and a queue of operations, then derives the visible
+ * state by replaying that queue.  Keeping those three concerns separate is what
+ * makes a restart, a rejected operation, and a remote snapshot converge to the
+ * same result.
+ */
+const RTL_DURABLE_SCHEMA_VERSION = 1;
+const RTL_RETRY_BASE_MS = 1000;
+const RTL_RETRY_MAX_MS = 60 * 1000;
+
+const rtlDurableIsObject = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+const rtlToFiniteNumber = (value, fallback = 0) => {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+};
+
+const rtlNormalizeUid = (value) => {
+  if (value === undefined || value === null) return null;
+  const uid = String(value).trim();
+  return uid || null;
+};
+
+const rtlNormalizeWorkspaceEpoch = (value, fallback = 0) => {
+  if (value === undefined || value === null || value === '') {
+    value = fallback;
+  }
+  const number = Number(value);
+  if (Number.isFinite(number)) return Math.max(0, Math.floor(number));
+  const fallbackNumber = Number(fallback);
+  return Number.isFinite(fallbackNumber)
+    ? Math.max(0, Math.floor(fallbackNumber))
+    : 0;
+};
+
+const rtlCloneOperation = (operation) => clone(operation && typeof operation === 'object' ? operation : {});
+
+const rtlStripSessionTokens = (value) => {
+  if (Array.isArray(value)) return value.map((entry) => rtlStripSessionTokens(entry));
+  if (!rtlDurableIsObject(value)) return value;
+  const result = {};
+  Object.entries(value).forEach(([key, entry]) => {
+    if (key === 'sessionToken' || key === 'sessionTokenId' || key === 'authToken') return;
+    result[key] = rtlStripSessionTokens(entry);
+  });
+  return result;
+};
+
+const rtlNormalizeOperation = (operation = {}, {
+  client,
+  clientId,
+  now,
+  ownerUid = null,
+  workspaceEpoch = 0
+} = {}) => {
+  const input = operation && typeof operation === 'object' ? operation : {};
+  const payload = rtlDurableIsObject(input.payload) ? clone(input.payload) : {};
+  const normalizedPayload = payload;
+  const trimPayloadId = (key) => {
+    if (Object.prototype.hasOwnProperty.call(normalizedPayload, key)) {
+      normalizedPayload[key] = normalizeId(normalizedPayload[key]) || normalizedPayload[key];
+    }
+  };
+  [
+    'recordId', 'folderId', 'targetFolderId', 'trashEntryId', 'batchId', 'id',
+    'clientInstanceId', 'instanceId'
+  ].forEach(trimPayloadId);
+  ['recordIds', 'folderOrder', 'groupOrder', 'expandedGroups', 'groupIds', 'ids'].forEach((key) => {
+    if (Array.isArray(normalizedPayload[key])) {
+      normalizedPayload[key] = normalizeIdList(normalizedPayload[key]);
+    }
+  });
+  if (rtlDurableIsObject(normalizedPayload.record)) {
+    normalizedPayload.record = clone(normalizedPayload.record);
+    if (Object.prototype.hasOwnProperty.call(normalizedPayload.record, 'id')) {
+      normalizedPayload.record.id = normalizeId(normalizedPayload.record.id) || normalizedPayload.record.id;
+    }
+    if (Object.prototype.hasOwnProperty.call(normalizedPayload.record, 'folderId')) {
+      normalizedPayload.record.folderId = normalizeId(normalizedPayload.record.folderId) || normalizedPayload.record.folderId;
+    }
+  }
+  if (rtlDurableIsObject(normalizedPayload.folder)) {
+    normalizedPayload.folder = clone(normalizedPayload.folder);
+    if (Object.prototype.hasOwnProperty.call(normalizedPayload.folder, 'id')) {
+      normalizedPayload.folder.id = normalizeId(normalizedPayload.folder.id) || normalizedPayload.folder.id;
+    }
+  }
+
+  const operationNow = rtlToFiniteNumber(input.createdAt, NaN);
+  const resolvedNow = Number.isFinite(operationNow)
+    ? operationNow
+    : (typeof now === 'function' ? now() : now);
+  const resolvedClientId = input.clientId || clientId ||
+    (typeof client === 'string' ? client : client?.id) || null;
+  const generatedId = createOperation(input.type, normalizedPayload, {
+    clientId: resolvedClientId || 'recordtimelabel-client',
+    now: Number.isFinite(Number(resolvedNow)) ? Number(resolvedNow) : Date.now()
+  }).id;
+
+  return {
+    ...rtlStripSessionTokens(input),
+    id: normalizeId(input.id) || generatedId,
+    type: typeof input.type === 'string' ? input.type.trim() : input.type,
+    payload: normalizedPayload,
+    clientId: resolvedClientId,
+    createdAt: Number.isFinite(Number(resolvedNow)) ? Number(resolvedNow) : Date.now(),
+    ownerUid: rtlNormalizeUid(input.ownerUid) || rtlNormalizeUid(ownerUid),
+    workspaceEpoch: rtlNormalizeWorkspaceEpoch(input.workspaceEpoch, workspaceEpoch)
+  };
+};
+
+const rtlNormalizePendingOperation = (operation, options = {}) => {
+  const normalized = rtlNormalizeOperation(operation, options);
+  const retryCount = Math.max(
+    0,
+    Math.floor(rtlToFiniteNumber(operation?.retryCount ?? operation?.retryAttempts, 0))
+  );
+  const nextRetryAt = rtlToFiniteNumber(operation?.nextRetryAt, NaN);
+  if (retryCount > 0) normalized.retryCount = retryCount;
+  if (Number.isFinite(nextRetryAt)) normalized.nextRetryAt = nextRetryAt;
+  return normalized;
+};
+
+const rtlNormalizeRemoteBaseline = (value = {}) => {
+  const baseline = rtlDurableIsObject(value) ? value : {};
+  return {
+    state: normalizeRecordTimeLabelDomainState(baseline.state || baseline.data || {}),
+    revision: Math.max(0, rtlToFiniteNumber(baseline.revision, 0)),
+    changeCursor: baseline.changeCursor === undefined || baseline.changeCursor === null
+      ? null
+      : String(baseline.changeCursor)
+  };
+};
+
+const rtlEmptyDurableWorkspace = ({ownerUid = null, workspaceEpoch = 0} = {}) => ({
+  schemaVersion: RTL_DURABLE_SCHEMA_VERSION,
+  ownerUid: rtlNormalizeUid(ownerUid),
+  workspaceEpoch: rtlNormalizeWorkspaceEpoch(workspaceEpoch, 0),
+  remoteBaseline: rtlNormalizeRemoteBaseline({}),
+  pendingOperations: [],
+  rejectedOperations: {},
+  syncMeta: {}
+});
+
+const rtlNormalizeDurableWorkspace = (input = {}, options = {}) => {
+  const source = rtlDurableIsObject(input) ? input : {};
+  const legacy = !source.remoteBaseline && (
+    Object.prototype.hasOwnProperty.call(source, 'state') ||
+    Object.prototype.hasOwnProperty.call(source, 'pendingOps')
+  );
+  const ownerUid = rtlNormalizeUid(source.ownerUid ?? options.ownerUid);
+  const workspaceEpoch = rtlNormalizeWorkspaceEpoch(
+    source.workspaceEpoch ?? options.workspaceEpoch,
+    options.workspaceEpoch
+  );
+  const baseline = legacy
+    ? rtlNormalizeRemoteBaseline({
+      state: source.state || {},
+      revision: source.revision ?? source.syncMeta?.revision,
+      changeCursor: source.changeCursor ?? source.syncMeta?.changeCursor
+    })
+    : rtlNormalizeRemoteBaseline(source.remoteBaseline || {});
+  const pendingSource = source.pendingOperations ?? source.pendingOps ?? [];
+  const pendingOperations = toArray(pendingSource)
+    .filter(Boolean)
+    .map((operation) => rtlNormalizePendingOperation(operation, options));
+  const legacyExpandedGroups = Array.isArray(source.syncMeta?.legacyExpandedGroups)
+    ? normalizeOrder(source.syncMeta.legacyExpandedGroups)
+    : Array.isArray(source.state?.expandedGroups)
+      ? normalizeOrder(source.state.expandedGroups)
+    : Array.isArray(source.remoteBaseline?.state?.expandedGroups)
+      ? normalizeOrder(source.remoteBaseline.state.expandedGroups)
+      : null;
+  const rejectedSource = rtlDurableIsObject(source.rejectedOperations) ? source.rejectedOperations : {};
+  const rejectedOperations = {};
+  Object.entries(rejectedSource).forEach(([rawId, value]) => {
+    const id = normalizeId(rawId || value?.id || value?.operationId);
+    if (!id) return;
+    rejectedOperations[id] = clone(value && typeof value === 'object' ? value : {reason: value});
+    if (rejectedOperations[id].operation) {
+      rejectedOperations[id].operation = rtlNormalizePendingOperation(
+        rejectedOperations[id].operation,
+        options
+      );
+    }
+  });
+  return {
+    schemaVersion: RTL_DURABLE_SCHEMA_VERSION,
+    ownerUid,
+    workspaceEpoch,
+    remoteBaseline: baseline,
+    pendingOperations,
+    rejectedOperations,
+    syncMeta: {
+      ...(rtlDurableIsObject(source.syncMeta) ? rtlStripSessionTokens(source.syncMeta) : {}),
+      ...(legacyExpandedGroups && !Array.isArray(source.syncMeta?.migratedExpandedGroups)
+        ? {legacyExpandedGroups}
+        : {})
+    }
+  };
+};
+
+const rtlOperationIdentityReason = (operation, workspace) => {
+  const operationOwnerUid = rtlNormalizeUid(operation?.ownerUid);
+  const workspaceOwnerUid = rtlNormalizeUid(workspace?.ownerUid);
+  if (operationOwnerUid && operationOwnerUid !== workspaceOwnerUid) {
+    return RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.OWNER_MISMATCH;
+  }
+  const operationEpoch = rtlNormalizeWorkspaceEpoch(
+    operation?.workspaceEpoch,
+    workspace?.workspaceEpoch
+  );
+  const workspaceEpoch = rtlNormalizeWorkspaceEpoch(workspace?.workspaceEpoch, 0);
+  if (operationEpoch !== workspaceEpoch) {
+    return RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.WORKSPACE_EPOCH_MISMATCH;
+  }
+  return null;
+};
+
+const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now()) => {
+  const accepted = [];
+  const rejected = {...(workspace?.rejectedOperations || {})};
+  let rejectedCount = 0;
+  toArray(operations).forEach((operation, index) => {
+    const reason = rtlOperationIdentityReason(operation, workspace);
+    if (!reason) {
+      accepted.push(operation);
+      return;
+    }
+    rejectedCount += 1;
+    const id = normalizeId(operation?.id) || `identity-rejected:${timestamp}:${index}`;
+    rejected[id] = {
+      id,
+      operation: clone(operation),
+      status: 'rejected',
+      reason,
+      rejectedAt: timestamp,
+      identity: {
+        operationOwnerUid: rtlNormalizeUid(operation?.ownerUid),
+        workspaceOwnerUid: rtlNormalizeUid(workspace?.ownerUid),
+        operationWorkspaceEpoch: rtlNormalizeWorkspaceEpoch(
+          operation?.workspaceEpoch,
+          workspace?.workspaceEpoch
+        ),
+        workspaceEpoch: rtlNormalizeWorkspaceEpoch(workspace?.workspaceEpoch, 0)
+      }
+    };
+  });
+  return {accepted, rejected, rejectedCount};
+};
+
+const rtlExtractSession = (session, fallbackEpoch = 0) => {
+  let current = null;
+  try {
+    current = typeof session?.current === 'function' ? session.current() : null;
+  } catch {
+    current = null;
+  }
+  // A session port is intentionally small and adapters use both token and
+  // sessionToken spellings.  Preserve the original token (including objects)
+  // for isCurrent, but never put it in a workspace blob.
+  const token = current && typeof current === 'object'
+    ? (current.sessionToken ?? current.token ?? current.id ?? current)
+    : current;
+  const uid = rtlNormalizeUid(current && typeof current === 'object'
+    ? (current.uid ?? current.ownerUid)
+    : null);
+  const rawEpoch = current && typeof current === 'object'
+    ? (current.workspaceEpoch ?? current.epoch)
+    : undefined;
+  const hasEpoch = rawEpoch !== undefined && rawEpoch !== null && Number.isFinite(Number(rawEpoch));
+  return {
+    current,
+    hasSession: typeof session?.current === 'function',
+    token,
+    sessionToken: token,
+    uid,
+    workspaceEpoch: hasEpoch
+      ? rtlNormalizeWorkspaceEpoch(rawEpoch, fallbackEpoch)
+      : rtlNormalizeWorkspaceEpoch(fallbackEpoch, 0),
+    hasEpoch
+  };
+};
+
+const rtlSessionContext = (captured, workspace, client) => ({
+  sessionToken: captured?.sessionToken ?? null,
+  token: captured?.token ?? null,
+  uid: captured?.uid ?? (captured?.hasSession ? null : workspace?.ownerUid ?? null),
+  ownerUid: captured?.uid ?? (captured?.hasSession ? null : workspace?.ownerUid ?? null),
+  workspaceEpoch: workspace?.workspaceEpoch ?? captured?.workspaceEpoch ?? 0,
+  client: clone(client)
+});
+
+const rtlEnvelopePayload = (value) => {
+  if (value && typeof value === 'object') {
+    if (value.remoteBaseline) return value.remoteBaseline;
+    if (value.baseline) return value.baseline;
+    if (value.state !== undefined || value.data !== undefined || value.revision !== undefined || value.changeCursor !== undefined) {
+      return value;
+    }
+    if (value.snapshot && typeof value.snapshot === 'object') return value.snapshot;
+    // Adapters migrating from the v1 cloud port may still return a raw
+    // normalized state. Treat the presence of state-owned keys as an implicit
+    // baseline with the persisted revision.
+    if (value.folders !== undefined || value.records !== undefined || value.settings !== undefined) {
+      return {state: value, revision: value.revision, changeCursor: value.changeCursor};
+    }
+  }
+  return null;
+};
+
+const rtlEnvelopeSuccess = (value) => {
+  if (!value || typeof value !== 'object') return false;
+  if (value.success === false || value.ok === false || value.error || value.code === 'error') return false;
+  return value.success === true || value.ok === true || (
+    value.success === undefined && value.ok === undefined && !value.error
+  );
+};
+
+const rtlRetryableEnvelopeError = (value) => {
+  const error = value?.error && typeof value.error === 'object' ? value.error : value;
+  const status = Number(error?.status ?? error?.statusCode ?? value?.status ?? value?.statusCode);
+  const code = String(error?.code ?? value?.code ?? '').toLowerCase();
+  return Boolean(
+    error?.retryable === true ||
+    value?.retryable === true ||
+    status === 408 || status === 409 || status === 425 || status === 429 || status >= 500 ||
+    code === 'bulk_job_in_progress' || code === 'retryable' || code === 'temporarily_unavailable' ||
+    code === 'unavailable' || code === 'deadline_exceeded'
+  );
+};
+
+const rtlRetryAfterMs = (value) => {
+  const error = value?.error && typeof value.error === 'object' ? value.error : value;
+  const retryAfter = Number(error?.retryAfterMs ?? value?.retryAfterMs);
+  return Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : null;
+};
+
+const rtlResultOperationId = (result = {}) => normalizeId(
+  result.id ?? result.operationId ?? result.opId ?? result.operation?.id
+);
+
+const rtlIsStaleRevision = (revision, baselineRevision) => (
+  Number.isFinite(Number(revision)) && Number(revision) < Number(baselineRevision)
+);
+
+const rtlDeriveDurableVisibleState = (workspace) => {
+  let state = normalizeRecordTimeLabelDomainState(workspace?.remoteBaseline?.state || {});
+  toArray(workspace?.pendingOperations).forEach((operation) => {
+    state = operation?.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE
+      ? state
+      : normalizeRecordTimeLabelDomainState(applyRecordTimeLabelOperation(state, operation));
+  });
+  return state;
+};
+
+const rtlDurableWorkspaceSnapshot = (workspace) => {
+  const persisted = clone(workspace);
+  const state = rtlDeriveDurableVisibleState(workspace);
+  return {
+    ...persisted,
+    state: clone(state),
+    visibleState: clone(state),
+    // These aliases make migration from the v1 engine less surprising while
+    // the persisted contract remains strictly pendingOperations-based.
+    pendingOps: clone(workspace.pendingOperations),
+    syncMeta: clone(workspace.syncMeta)
+  };
+};
+
+export const createRecordTimeLabelSyncEngine = ({
+  storage,
+  cloud,
+  session,
+  client = 'recordtimelabel-client',
+  clock = () => Date.now(),
+  logger = console
+} = {}) => {
+  if (!storage?.load || !storage?.save) {
+    throw new Error('createRecordTimeLabelSyncEngine requires storage.load() and storage.save()');
+  }
+
+  let workspace = rtlEmptyDurableWorkspace();
+  let initialized = false;
+  let destroyed = false;
+  let unsubscribeCloud = null;
+  let unsubscribeSession = null;
+  let subscriptionContext = null;
+  const listeners = new Set();
+  let queue = Promise.resolve();
+
+  const now = () => {
+    try {
+      const value = typeof clock === 'function' ? clock() : clock;
+      return Number.isFinite(Number(value)) ? Number(value) : Date.now();
+    } catch {
+      return Date.now();
+    }
+  };
+
+  const getSnapshot = () => rtlDurableWorkspaceSnapshot(workspace);
+
+  const notify = (event = {}) => {
+    if (destroyed) return;
+    const snapshot = getSnapshot();
+    listeners.forEach((listener) => {
+      try {
+        listener({...event, snapshot: clone(snapshot)});
+      } catch (error) {
+        logger?.error?.('[RecordTimeLabelCore] durable listener failed', error);
+      }
+    });
+  };
+
+  const enqueue = (task) => {
+    const run = queue.then(async () => {
+      if (destroyed) return {stale: true, reason: 'destroyed'};
+      return task();
+    });
+    queue = run.catch(() => {});
+    return run;
+  };
+
+  const capture = () => rtlExtractSession(session, workspace.workspaceEpoch);
+
+  const isCurrent = async (captured) => {
+    if (destroyed || !captured) return false;
+    if (typeof session?.isCurrent === 'function') {
+      try {
+        return Boolean(await session.isCurrent(
+          captured.sessionToken,
+          captured.uid,
+          captured.workspaceEpoch
+        ));
+      } catch {
+        return false;
+      }
+    }
+    if (typeof session?.current !== 'function') return true;
+    const current = rtlExtractSession(session, captured.workspaceEpoch);
+    if (captured.token !== undefined && captured.token !== null && current.token !== captured.token) return false;
+    if (captured.uid !== current.uid) return false;
+    return !captured.hasEpoch || current.workspaceEpoch === captured.workspaceEpoch;
+  };
+
+  const persist = async (candidate, captured) => {
+    if (!(await isCurrent(captured))) return false;
+    // The second argument is an optional adapter-side fence.  The public
+    // StoragePort remains compatible with save(workspace); adapters that can
+    // enforce an atomic session/epoch check should consume this context before
+    // mutating durable storage.
+    await storage.save(clone(candidate), {
+      sessionToken: captured?.sessionToken ?? null,
+      uid: captured?.uid ?? null,
+      ownerUid: captured?.uid ?? null,
+      workspaceEpoch: captured?.workspaceEpoch ?? candidate.workspaceEpoch
+    });
+    if (!(await isCurrent(captured))) return false;
+    return true;
+  };
+
+  const applyRemoteBaseline = (candidate, remoteValue) => {
+    const remote = rtlEnvelopePayload(remoteValue);
+    if (!remote) return {changed: false, stale: false};
+    const revision = Number(remote.revision);
+    if (rtlIsStaleRevision(revision, candidate.remoteBaseline.revision)) {
+      return {changed: false, stale: true};
+    }
+    const nextBaseline = rtlNormalizeRemoteBaseline({
+      state: remote.state ?? remote.data ?? candidate.remoteBaseline.state,
+      revision: Number.isFinite(revision) ? revision : candidate.remoteBaseline.revision,
+      changeCursor: Object.prototype.hasOwnProperty.call(remote, 'changeCursor')
+        ? remote.changeCursor
+        : candidate.remoteBaseline.changeCursor
+    });
+    const changed = JSON.stringify(nextBaseline) !== JSON.stringify(candidate.remoteBaseline);
+    candidate.remoteBaseline = nextBaseline;
+    return {changed, stale: false};
+  };
+
+  const normalizeLoadedWorkspace = (loaded, captured) => {
+    const source = loaded && typeof loaded === 'object' ? loaded : {};
+    const hasDurableShape = source.remoteBaseline || source.pendingOperations || source.schemaVersion === RTL_DURABLE_SCHEMA_VERSION;
+    const sourceOwnerUid = rtlNormalizeUid(source.ownerUid);
+    const sourcePending = toArray(source.pendingOperations ?? source.pendingOps);
+    const sourceHasBoundOperation = sourcePending.some((operation) => rtlNormalizeUid(operation?.ownerUid));
+    const loadedWorkspace = rtlNormalizeDurableWorkspace(
+      hasDurableShape ? source : {
+        ...source,
+        state: source.state || source,
+        pendingOps: source.pendingOps || source.pendingOperations || [],
+        syncMeta: source.syncMeta || {}
+      },
+      {
+        ownerUid: captured?.uid,
+        workspaceEpoch: captured?.workspaceEpoch,
+        client,
+        now
+      }
+    );
+    const currentUid = captured?.uid;
+    const currentEpoch = captured?.workspaceEpoch ?? loadedWorkspace.workspaceEpoch;
+    const anonymousMigration = Boolean(
+      currentUid &&
+      !sourceOwnerUid &&
+      !sourceHasBoundOperation &&
+      !loadedWorkspace.syncMeta?.anonymousMigrationAt
+    );
+    if (anonymousMigration) {
+      const anonymousState = loadedWorkspace.remoteBaseline.state;
+      const migrationTime = Math.max(1, rtlToFiniteNumber(anonymousState.lastModified, now()));
+      const migratedOperations = [];
+      const seenIds = new Set();
+      const addMigrationOperation = (type, payload, id) => {
+        const normalizedId = normalizeId(id);
+        if (!normalizedId || seenIds.has(normalizedId)) return;
+        seenIds.add(normalizedId);
+        migratedOperations.push(rtlNormalizePendingOperation({
+          id: normalizedId,
+          type,
+          payload,
+          clientId: 'anonymous-migration',
+          createdAt: migrationTime
+        }, {
+          client,
+          now,
+          ownerUid: currentUid,
+          workspaceEpoch: currentEpoch
+        }));
+      };
+      toArray(anonymousState.folders).forEach((folder) => {
+        const id = normalizeId(folder?.id);
+        if (!id || id === 'all' || id === 'uncategorized') return;
+        addMigrationOperation(
+          OPERATION_TYPES.FOLDER_CREATE,
+          {folder: clone(folder)},
+          `anonymous:folder.create:${id}`
+        );
+      });
+      Object.entries(anonymousState.records || {}).forEach(([folderId, records]) => {
+        if (folderId === 'all') return;
+        toArray(records).forEach((record) => {
+          const id = normalizeId(record?.id);
+          if (!id) return;
+          const migratedRecord = clone(record);
+          if (migratedRecord && typeof migratedRecord === 'object') {
+            delete migratedRecord.pendingSync;
+            delete migratedRecord.syncAttempts;
+          }
+          addMigrationOperation(
+            OPERATION_TYPES.RECORD_CREATE,
+            {folderId, record: migratedRecord},
+            `anonymous:record.create:${id}`
+          );
+        });
+      });
+      loadedWorkspace.remoteBaseline = rtlNormalizeRemoteBaseline({});
+      loadedWorkspace.pendingOperations = [
+        ...migratedOperations,
+        ...loadedWorkspace.pendingOperations
+          .filter((operation) => (
+            operation?.type === OPERATION_TYPES.FOLDER_CREATE ||
+            operation?.type === OPERATION_TYPES.RECORD_CREATE
+          ))
+          .map((operation) => rtlNormalizePendingOperation(operation, {
+            client,
+            now,
+            ownerUid: currentUid,
+            workspaceEpoch: currentEpoch
+          }))
+      ];
+      loadedWorkspace.ownerUid = currentUid;
+      loadedWorkspace.workspaceEpoch = currentEpoch;
+      loadedWorkspace.syncMeta = {
+        ...loadedWorkspace.syncMeta,
+        anonymousMigrationAt: now(),
+        anonymousMigrationMode: 'create_only'
+      };
+    }
+    const ownerMismatch = captured?.hasSession && loadedWorkspace.ownerUid !== currentUid && !anonymousMigration;
+    const epochMismatch = Boolean(
+      captured?.hasEpoch && Number(loadedWorkspace.workspaceEpoch) !== Number(currentEpoch)
+    );
+    if (ownerMismatch || epochMismatch) {
+      return rtlEmptyDurableWorkspace({ownerUid: currentUid, workspaceEpoch: currentEpoch});
+    }
+    const currentView = Array.isArray(loadedWorkspace.syncMeta?.migratedExpandedGroups)
+      ? loadedWorkspace.syncMeta.migratedExpandedGroups
+      : loadedWorkspace.syncMeta?.legacyExpandedGroups || [];
+    const migratedView = migrateRecordTimeLabelExpandedGroups({
+      pendingOperations: loadedWorkspace.pendingOperations,
+      currentView
+    });
+    const hadLegacyView = migratedView.pendingOperations.length !==
+      loadedWorkspace.pendingOperations.length ||
+      Object.prototype.hasOwnProperty.call(loadedWorkspace.syncMeta || {}, 'legacyExpandedGroups');
+    loadedWorkspace.pendingOperations = migratedView.pendingOperations;
+    loadedWorkspace.remoteBaseline.state = normalizeRecordTimeLabelDomainState(
+      loadedWorkspace.remoteBaseline.state
+    );
+    if (hadLegacyView) {
+      const syncMeta = {...loadedWorkspace.syncMeta};
+      delete syncMeta.legacyExpandedGroups;
+      loadedWorkspace.syncMeta = {
+        ...syncMeta,
+        migratedExpandedGroups: migratedView.expandedGroups,
+        expandedGroupsMigrationAt: now()
+      };
+    }
+    loadedWorkspace.ownerUid = currentUid ?? loadedWorkspace.ownerUid;
+    if (captured?.hasEpoch) loadedWorkspace.workspaceEpoch = currentEpoch;
+    return loadedWorkspace;
+  };
+
+  const normalizeOperationResults = (response, sentOperations) => {
+    let results;
+    try {
+      // Keep the Plan 017 engine's private input aliases compatible while the
+      // public shared contract remains strict about operationResults arrays.
+      const legacyOperationResults = response?.operationResults;
+      const compatibleResponse = rtlDurableIsObject(legacyOperationResults)
+        ? {
+          ...response,
+          operationResults: Object.entries(legacyOperationResults).map(([id, result]) => ({
+            ...(result || {}),
+            id: result?.id || id
+          }))
+        }
+        : (
+          !Object.prototype.hasOwnProperty.call(response || {}, 'operationResults') &&
+          Array.isArray(response?.results)
+            ? {...response, operationResults: response.results}
+            : response
+        );
+      results = normalizeRecordTimeLabelEnvelopeResponse(sentOperations, compatibleResponse);
+    } catch (error) {
+      return {error, results: null};
+    }
+    const byId = new Map(sentOperations.map((operation) => [operation.id, operation]));
+    const normalized = [];
+    const seen = new Set();
+    for (let index = 0; index < results.length; index += 1) {
+      const result = results[index] || {};
+      const resultId = rtlResultOperationId(result) || sentOperations[index]?.id;
+      if (!resultId || !byId.has(resultId) || seen.has(resultId)) {
+        return {error: new Error('sync_protocol_invalid_operation_result'), results: null};
+      }
+      seen.add(resultId);
+      normalized.push({...clone(result), id: resultId});
+    }
+    if (seen.size !== sentOperations.length) {
+      return {error: new Error('sync_protocol_operation_result_count_mismatch'), results: null};
+    }
+    return {results: normalized};
+  };
+
+  const operationRetryAt = (operation, result, retryAfterMs, timestamp) => {
+    const direct = Number(result?.nextRetryAt);
+    if (Number.isFinite(direct)) return direct;
+    const after = Number(result?.retryAfterMs ?? retryAfterMs);
+    if (Number.isFinite(after) && after >= 0) return timestamp + after;
+    const attempts = Math.max(0, Number(operation?.retryCount || operation?.retryAttempts || 0));
+    return timestamp + Math.min(RTL_RETRY_MAX_MS, RTL_RETRY_BASE_MS * (2 ** attempts));
+  };
+
+  const makeRetryOperation = (operation, result, retryAfterMs, timestamp) => ({
+    ...rtlCloneOperation(operation),
+    retryCount: Math.max(0, Number(operation?.retryCount || operation?.retryAttempts || 0)) + 1,
+    nextRetryAt: operationRetryAt(operation, result, retryAfterMs, timestamp)
+  });
+
+  const processRemote = async (remoteValue, captured) => {
+    if (!(await isCurrent(captured))) return {stale: true, reason: 'stale_session'};
+    const candidate = clone(workspace);
+    const applied = applyRemoteBaseline(candidate, remoteValue);
+    if (applied.stale || !applied.changed) return {success: true, ignored: true};
+    if (!(await persist(candidate, captured))) return {stale: true, reason: 'stale_session'};
+    workspace = candidate;
+    notify({type: 'remote_merged'});
+    return getSnapshot();
+  };
+
+  const initialize = async () => {
+    const captured = capture();
+    const loaded = await storage.load();
+    if (!(await isCurrent(captured))) return getSnapshot();
+    let candidate = normalizeLoadedWorkspace(loaded, captured);
+    const identityChecked = rtlQuarantineOperations(
+      candidate,
+      candidate.pendingOperations,
+      now()
+    );
+    candidate.pendingOperations = identityChecked.accepted;
+    candidate.rejectedOperations = identityChecked.rejected;
+    const context = rtlSessionContext(captured, candidate, client);
+
+    if (captured?.uid && typeof cloud?.bootstrap === 'function') {
+      let bootstrap;
+      try {
+        bootstrap = await cloud.bootstrap(context);
+      } catch (error) {
+        if (!(await isCurrent(captured))) return getSnapshot();
+        throw error;
+      }
+      if (!(await isCurrent(captured))) return getSnapshot();
+      applyRemoteBaseline(candidate, bootstrap);
+    }
+
+    // Always persist the normalized durable shape before subscribing.  This
+    // also makes legacy migration atomic from the engine's point of view.
+    if (!(await persist(candidate, captured))) return getSnapshot();
+    workspace = candidate;
+    initialized = true;
+
+    if (typeof cloud?.subscribe === 'function') {
+      subscriptionContext = context;
+      unsubscribeCloud = cloud.subscribe((remoteValue) => {
+        if (destroyed) return;
+        return enqueue(() => processRemote(remoteValue, captured)).catch((error) => {
+          logger?.error?.('[RecordTimeLabelCore] durable remote callback failed', error);
+          return {success: false, error};
+        });
+      }, context);
+    }
+    if (typeof session?.subscribe === 'function' && !unsubscribeSession) {
+      unsubscribeSession = session.subscribe(() => {});
+    }
+    notify({type: 'initialized'});
+    return getSnapshot();
+  };
+
+  const dispatchInternal = async (operations) => {
+    const captured = capture();
+    if (!(await isCurrent(captured))) return getSnapshot();
+    const input = Array.isArray(operations)
+      ? operations
+      : (operations && typeof operations === 'object' ? [operations] : []);
+    if (input.length === 0) return getSnapshot();
+    const candidate = clone(workspace);
+    if (captured?.uid !== undefined && captured?.uid !== null) {
+      candidate.ownerUid = captured.uid;
+    }
+    if (captured?.hasEpoch) candidate.workspaceEpoch = captured.workspaceEpoch;
+    const normalized = input.map((operation) => rtlNormalizePendingOperation(operation, {
+      client,
+      clientId: typeof client === 'string' ? client : client?.id,
+      now,
+      ownerUid: captured?.uid ?? candidate.ownerUid,
+      workspaceEpoch: captured?.workspaceEpoch ?? candidate.workspaceEpoch
+    }));
+    const identityChecked = rtlQuarantineOperations(candidate, normalized, now());
+    const viewOperations = identityChecked.accepted.filter((operation) => (
+      operation.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE
+    ));
+    const durableOperations = identityChecked.accepted.filter((operation) => (
+      operation.type !== OPERATION_TYPES.EXPANDED_GROUPS_UPDATE
+    ));
+    const viewMigration = migrateRecordTimeLabelExpandedGroups({
+      pendingOperations: viewOperations,
+      currentView: candidate.syncMeta?.migratedExpandedGroups || []
+    });
+    candidate.pendingOperations = [
+      ...candidate.pendingOperations,
+      ...durableOperations
+    ];
+    candidate.rejectedOperations = identityChecked.rejected;
+    if (viewOperations.length > 0) {
+      candidate.syncMeta = {
+        ...candidate.syncMeta,
+        migratedExpandedGroups: viewMigration.expandedGroups,
+        expandedGroupsMigrationAt: now(),
+        lastLocalViewOperationAt: viewOperations[viewOperations.length - 1].createdAt,
+        lastLocalViewOperationId: viewOperations[viewOperations.length - 1].id
+      };
+    }
+    if (durableOperations.length > 0) {
+      const lastOperation = durableOperations[durableOperations.length - 1];
+      candidate.syncMeta = {
+        ...candidate.syncMeta,
+        lastLocalOperationAt: lastOperation.createdAt,
+        lastLocalOperationId: lastOperation.id,
+        lastLocalOperationType: lastOperation.type
+      };
+    }
+    if (!(await persist(candidate, captured))) return getSnapshot();
+    workspace = candidate;
+    if (durableOperations.length > 0 || viewOperations.length > 0) {
+      notify({
+        type: 'local_applied',
+        operations: clone([...durableOperations, ...viewOperations]),
+        operation: clone(viewOperations.at(-1) || durableOperations.at(-1)),
+        rejectedCount: identityChecked.rejectedCount
+      });
+    } else {
+      notify({type: 'operations_rejected', rejectedCount: identityChecked.rejectedCount});
+    }
+    return getSnapshot();
+  };
+
+  const syncInternal = async (reason) => {
+    const captured = capture();
+    if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
+    const timestamp = now();
+    const identityChecked = rtlQuarantineOperations(
+      workspace,
+      workspace.pendingOperations,
+      timestamp
+    );
+    let identityRejectedCount = identityChecked.rejectedCount;
+    if (identityRejectedCount > 0) {
+      const candidate = clone(workspace);
+      candidate.pendingOperations = identityChecked.accepted;
+      candidate.rejectedOperations = identityChecked.rejected;
+      candidate.syncMeta = {
+        ...candidate.syncMeta,
+        lastIdentityRejectionAt: timestamp,
+        lastIdentityRejectionCount: identityRejectedCount
+      };
+      if (!(await persist(candidate, captured))) return {success: false, reason: 'stale_session'};
+      workspace = candidate;
+      notify({type: 'operations_rejected', rejectedCount: identityRejectedCount});
+    }
+    const ready = workspace.pendingOperations.filter((operation) => (
+      !Number.isFinite(Number(operation.nextRetryAt)) || Number(operation.nextRetryAt) <= timestamp
+    ));
+    if (ready.length === 0) {
+      return {
+        success: true,
+        skipped: workspace.pendingOperations.length > 0 ? 'retry_deadline' : 'empty',
+        pendingCount: workspace.pendingOperations.length,
+        rejectedCount: identityRejectedCount,
+        identityRejectedCount
+      };
+    }
+    if (!captured?.uid) {
+      return {
+        success: true,
+        skipped: 'anonymous',
+        pendingCount: workspace.pendingOperations.length,
+        rejectedCount: identityRejectedCount,
+        identityRejectedCount
+      };
+    }
+    if (typeof cloud?.applyOperations !== 'function') {
+      return {success: false, reason: 'missing_cloud_apply_operations'};
+    }
+    const context = rtlSessionContext(captured, workspace, client);
+    let response;
+    try {
+      response = await cloud.applyOperations({
+        schemaVersion: RTL_DURABLE_SCHEMA_VERSION,
+        ownerUid: workspace.ownerUid,
+        workspaceEpoch: workspace.workspaceEpoch,
+        client: clone(client),
+        reason: reason ?? null,
+        operations: clone(ready)
+      }, context);
+    } catch (error) {
+      if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
+      if (!rtlRetryableEnvelopeError(error)) {
+        logger?.error?.('[RecordTimeLabelCore] durable sync failed', error);
+        return {success: false, error};
+      }
+      response = {
+        success: false,
+        error,
+        retryAfterMs: rtlRetryAfterMs(error)
+      };
+    }
+    if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
+
+    if (!rtlEnvelopeSuccess(response)) {
+      if (!rtlRetryableEnvelopeError(response)) {
+        const error = response?.error instanceof Error
+          ? response.error
+          : new Error(response?.error?.message || response?.message || response?.code || 'sync_envelope_failed');
+        logger?.error?.('[RecordTimeLabelCore] durable sync envelope failed', error);
+        return {success: false, error};
+      }
+      const retryAfterMs = rtlRetryAfterMs(response);
+      const candidate = clone(workspace);
+      const byId = new Set(ready.map((operation) => operation.id));
+      candidate.pendingOperations = candidate.pendingOperations.map((operation) => (
+        byId.has(operation.id)
+          ? makeRetryOperation(operation, response, retryAfterMs, timestamp)
+          : operation
+      ));
+      candidate.syncMeta = {
+        ...candidate.syncMeta,
+        lastSyncAttemptAt: timestamp,
+        lastSyncError: response?.error?.message || response?.message || response?.code || 'retryable'
+      };
+      if (!(await persist(candidate, captured))) return {success: false, reason: 'stale_session'};
+      workspace = candidate;
+      notify({type: 'sync_retry', reason: response?.error?.code || response?.code || 'retryable'});
+      const retryAt = Math.min(...candidate.pendingOperations
+        .filter((operation) => Number.isFinite(Number(operation.nextRetryAt)))
+        .map((operation) => Number(operation.nextRetryAt)));
+      return {
+        success: false,
+        retryable: true,
+        retryAfterMs,
+        retryAt: Number.isFinite(retryAt) ? retryAt : null,
+        pendingCount: workspace.pendingOperations.length,
+        identityRejectedCount
+      };
+    }
+
+    const parsed = normalizeOperationResults(response, ready);
+    if (parsed.error) {
+      logger?.error?.('[RecordTimeLabelCore] durable sync protocol error', parsed.error);
+      return {success: false, error: parsed.error, protocolError: true};
+    }
+    const candidate = clone(workspace);
+    const resultById = new Map(parsed.results.map((result) => [result.id, result]));
+    const readyIds = new Set(ready.map((operation) => operation.id));
+    const appliedOperations = [];
+    const nextPending = [];
+    const nextRejected = {...candidate.rejectedOperations};
+    for (const operation of candidate.pendingOperations) {
+      if (!readyIds.has(operation.id)) {
+        nextPending.push(operation);
+        continue;
+      }
+      const result = resultById.get(operation.id);
+      if (result.status === 'applied') {
+        appliedOperations.push(operation);
+      } else if (result.status === 'noop') {
+        // A noop is acknowledged but intentionally not promoted onto the
+        // baseline: the server says the operation had no effect.
+      } else if (result.status === 'retryable') {
+        nextPending.push(makeRetryOperation(operation, result, null, timestamp));
+      } else if (result.status === 'rejected') {
+        nextRejected[operation.id] = {
+          id: operation.id,
+          operation: clone(operation),
+          status: 'rejected',
+          reason: result.reason ?? result.error ?? result.code ?? 'rejected',
+          rejectedAt: timestamp,
+          response: rtlStripSessionTokens(result)
+        };
+      }
+    }
+    appliedOperations.forEach((operation) => {
+      candidate.remoteBaseline.state = normalizeRecordTimeLabelDomainState(
+        applyRecordTimeLabelOperation(candidate.remoteBaseline.state, operation)
+      );
+    });
+    const responseRevision = Number(response.revision ?? response.remoteRevision);
+    if (Number.isFinite(responseRevision) && responseRevision >= candidate.remoteBaseline.revision) {
+      candidate.remoteBaseline.revision = responseRevision;
+    }
+    if (Object.prototype.hasOwnProperty.call(response || {}, 'changeCursor')) {
+      candidate.remoteBaseline.changeCursor = response.changeCursor === null || response.changeCursor === undefined
+        ? null
+        : String(response.changeCursor);
+    }
+    candidate.pendingOperations = nextPending;
+    candidate.rejectedOperations = nextRejected;
+    candidate.syncMeta = {
+      ...candidate.syncMeta,
+      lastSyncedAt: timestamp,
+      lastSyncAttemptAt: timestamp,
+      lastSyncReason: reason ?? null,
+      lastSyncError: null
+    };
+    if (!(await persist(candidate, captured))) return {success: false, reason: 'stale_session'};
+    workspace = candidate;
+    notify({type: 'synced', operations: clone(parsed.results)});
+    const retryAt = Math.min(...candidate.pendingOperations
+      .filter((operation) => Number.isFinite(Number(operation.nextRetryAt)))
+      .map((operation) => Number(operation.nextRetryAt)));
+    return {
+        success: true,
+      appliedCount: appliedOperations.length,
+      syncedCount: appliedOperations.length + parsed.results.filter((result) => result.status === 'noop').length,
+      rejectedCount: parsed.results.filter((result) => result.status === 'rejected').length,
+      retryCount: parsed.results.filter((result) => result.status === 'retryable').length,
+      retryAt: Number.isFinite(retryAt) ? retryAt : null,
+      pendingCount: workspace.pendingOperations.length,
+      identityRejectedCount
+    };
+  };
+
+  const engine = {
+    init() {
+      return enqueue(async () => {
+        if (initialized) return getSnapshot();
+        return initialize();
+      });
+    },
+
+    dispatch(operations) {
+      return enqueue(() => dispatchInternal(operations));
+    },
+
+    sync(reason) {
+      return enqueue(() => syncInternal(reason));
+    },
+
+    getSnapshot,
+
+    subscribe(listener) {
+      if (typeof listener !== 'function') return () => {};
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    destroy() {
+      destroyed = true;
+      initialized = false;
+      if (typeof unsubscribeCloud === 'function') {
+        try { unsubscribeCloud(); } catch (error) { logger?.error?.('[RecordTimeLabelCore] durable unsubscribe failed', error); }
+      }
+      if (typeof unsubscribeSession === 'function') {
+        try { unsubscribeSession(); } catch (error) { logger?.error?.('[RecordTimeLabelCore] durable session unsubscribe failed', error); }
+      }
+      unsubscribeCloud = null;
+      unsubscribeSession = null;
+      subscriptionContext = null;
+      listeners.clear();
+    }
+  };
+
+  return engine;
+};
+
 export const createSyncEngine = ({
   storageAdapter,
   cloudAdapter,
@@ -2622,16 +3816,23 @@ const rtlOperationFolderId = (operation = {}) => normalizeId(
 const rtlOperationTrashEntryId = (operation = {}) => normalizeId(
   operation?.payload?.trashEntryId || operation?.payload?.id
 );
+const rtlLifecycleTombstoneDocumentId = (kind, entityId) => (
+  encodeURIComponent(`${kind}:${normalizeId(entityId)}`)
+);
 const rtlCloneDocuments = (documents = {}) => ({
   root: clone(documents.root || null),
   records: clone(documents.records || {}),
   folders: clone(documents.folders || {}),
   trash: clone(documents.trash || {}),
+  lifecycleTombstones: clone(documents.lifecycleTombstones || {}),
   ops: {}
 });
 const rtlMergeOrder = (...orders) => normalizeOrder(orders.flatMap((order) => toArray(order)));
-const rtlNormalizeGroupOrder = (order) => rtlMergeOrder(order)
-  .filter((id) => id.startsWith('group-'));
+/**
+ * Group order ids are opaque to this package — mergeLocalRemote deliberately stops filtering them,
+ * so the planner must not drop ids on a prefix guess either.
+ */
+const rtlNormalizeGroupOrder = (order) => rtlMergeOrder(order);
 const rtlPayloadOrder = (operation, keys) => {
   for (const key of keys) {
     if (Array.isArray(operation?.payload?.[key])) return operation.payload[key];
@@ -2811,13 +4012,17 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
   const folderIds = new Set();
   const folderDeleteIds = new Set();
   const trashEntryIds = new Set();
+  const lifecycleTombstoneIds = new Set();
   toArray(operations).filter(Boolean).forEach((operation) => {
     const payload = operation.payload || {};
     switch (operation.type) {
       case OPERATION_TYPES.RECORD_CREATE:
       case OPERATION_TYPES.RECORD_MOVE: {
         const recordId = rtlOperationRecordId(operation);
-        if (recordId) recordIds.add(recordId);
+        if (recordId) {
+          recordIds.add(recordId);
+          lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('record', recordId));
+        }
         folderIds.add(safeFolderId(
           payload.targetFolderId || payload.folderId || payload.record?.folderId
         ));
@@ -2826,7 +4031,10 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
       case OPERATION_TYPES.RECORD_UPDATE:
       case OPERATION_TYPES.RECORD_DELETE: {
         const recordId = rtlOperationRecordId(operation);
-        if (recordId) recordIds.add(recordId);
+        if (recordId) {
+          recordIds.add(recordId);
+          lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('record', recordId));
+        }
         break;
       }
       case OPERATION_TYPES.RECORD_RESTORE:
@@ -2842,7 +4050,10 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
       case OPERATION_TYPES.FOLDER_UPDATE:
       case OPERATION_TYPES.FOLDER_DELETE: {
         const folderId = rtlOperationFolderId(operation);
-        if (folderId) folderIds.add(folderId);
+        if (folderId) {
+          folderIds.add(folderId);
+          lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('folder', folderId));
+        }
         if (folderId && operation.type === OPERATION_TYPES.FOLDER_DELETE) {
           folderDeleteIds.add(folderId);
         }
@@ -2852,7 +4063,7 @@ export const buildFirestoreV2OperationReadPlan = (operations = []) => {
         break;
     }
   });
-  return {recordIds, folderIds, folderDeleteIds, trashEntryIds};
+  return {recordIds, folderIds, folderDeleteIds, trashEntryIds, lifecycleTombstoneIds};
 };
 
 export const extendFirestoreV2OperationReadPlanWithRecords = (readPlan, records = {}) => {
@@ -2860,7 +4071,8 @@ export const extendFirestoreV2OperationReadPlanWithRecords = (readPlan, records
     recordIds: new Set(readPlan?.recordIds || []),
     folderIds: new Set(readPlan?.folderIds || []),
     folderDeleteIds: new Set(readPlan?.folderDeleteIds || []),
-    trashEntryIds: new Set(readPlan?.trashEntryIds || [])
+    trashEntryIds: new Set(readPlan?.trashEntryIds || []),
+    lifecycleTombstoneIds: new Set(readPlan?.lifecycleTombstoneIds || [])
   };
   Object.values(records || {}).forEach((record) => {
     next.folderIds.add(safeFolderId(record?.folderId));
@@ -2873,18 +4085,40 @@ export const extendFirestoreV2OperationReadPlanWithTrash = (readPlan, trashEntri
     recordIds: new Set(readPlan?.recordIds || []),
     folderIds: new Set(readPlan?.folderIds || []),
     folderDeleteIds: new Set(readPlan?.folderDeleteIds || []),
-    trashEntryIds: new Set(readPlan?.trashEntryIds || [])
+    trashEntryIds: new Set(readPlan?.trashEntryIds || []),
+    lifecycleTombstoneIds: new Set(readPlan?.lifecycleTombstoneIds || [])
   };
   Object.values(trashEntries || {}).forEach((entry) => {
-    if (entry?.kind === 'record') next.folderIds.add(safeFolderId(entry.originalFolderId));
+    const entityId = normalizeId(entry?.entityId);
+    if (entry?.kind === 'record') {
+      next.folderIds.add(safeFolderId(entry.originalFolderId));
+      if (entityId) {
+        next.lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('record', entityId));
+      }
+    } else if (entry?.kind === 'folder' && entityId) {
+      next.lifecycleTombstoneIds.add(rtlLifecycleTombstoneDocumentId('folder', entityId));
+    }
   });
   next.folderIds.add(DEFAULT_FOLDER_ID);
   return next;
 };
 
-const rtlApplyOperationToPartialDocuments = ({root, records, folders, trash, operation, now}) => {
+const rtlApplyOperationToPartialDocuments = ({
+  root,
+  records,
+  folders,
+  trash,
+  lifecycleTombstones,
+  operation,
+  now
+}) => {
   const {state} = buildStateFromFirestoreV2Documents({
-    root: root || {}, records: records || {}, folders: folders || {}, trash: trash || {}, ops: {}
+    root: root || {},
+    records: records || {},
+    folders: folders || {},
+    trash: trash || {},
+    lifecycleTombstones: lifecycleTombstones || {},
+    ops: {}
   });
   const nextState = applyRecordTimeLabelOperation(state, operation);
   return {
@@ -2936,6 +4170,10 @@ export const planFirestoreV2OperationChanges = ({
 } = {}) => {
   const previousDocuments = rtlCloneDocuments(documents);
   const nextDocuments = rtlCloneDocuments(documents);
+  const preservedExpandedGroups = previousDocuments.root &&
+    Object.prototype.hasOwnProperty.call(previousDocuments.root, 'expandedGroups')
+    ? clone(previousDocuments.root.expandedGroups)
+    : undefined;
   const normalizedLocalState = normalizeState(localState || {});
   const operationResults = [];
   let changed = false;
@@ -2944,12 +4182,23 @@ export const planFirestoreV2OperationChanges = ({
   }
 
   for (const operation of toArray(operations).filter(Boolean)) {
+    if (operation?.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE) {
+      operationResults.push({
+        id: operation.id || null,
+        type: operation.type,
+        applied: false,
+        status: 'noop',
+        reason: 'local_view_state'
+      });
+      continue;
+    }
     const payload = operation.payload || {};
     const operationNow = toFiniteTimestamp(operation.createdAt || payload.updatedAt) || now;
     const recordId = rtlOperationRecordId(operation);
     const folderId = rtlOperationFolderId(operation);
     let applied = null;
     let reason = null;
+    let lifecycleTombstoneId = null;
 
     switch (operation.type) {
       case OPERATION_TYPES.RECORD_CREATE: {
@@ -3012,25 +4261,28 @@ export const planFirestoreV2OperationChanges = ({
         });
         const recordDocument = applied.documents.records[recordId];
         if (!recordDocument) { reason = 'record_not_found'; break; }
+        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'; break; }
-        rtlSetRoot(nextDocuments.root, applied.documents.root);
-        nextDocuments.records[recordId] = recordDocument;
-        if (nextDocuments.folders[sourceFolderId]) {
-          nextDocuments.folders[sourceFolderId].recordOrder = rtlMergeOrder(
-            nextDocuments.folders[sourceFolderId].recordOrder
+        if (candidateFolders[sourceFolderId]) {
+          candidateFolders[sourceFolderId].recordOrder = rtlMergeOrder(
+            candidateFolders[sourceFolderId].recordOrder
           ).filter((id) => id !== recordId);
         }
         targetFolder.recordOrder = [
           ...rtlMergeOrder(targetFolder.recordOrder).filter((id) => id !== recordId),
           recordId
         ];
+        rtlSetRoot(nextDocuments.root, candidateRoot);
+        nextDocuments.folders = candidateFolders;
+        nextDocuments.records[recordId] = recordDocument;
         changed = true;
         break;
       }
@@ -3050,6 +4302,7 @@ export const planFirestoreV2OperationChanges = ({
       }
       case OPERATION_TYPES.RECORD_DELETE: {
         if (!recordId) { reason = 'missing_record_id'; break; }
+        lifecycleTombstoneId = rtlLifecycleTombstoneDocumentId('record', recordId);
         const sourceFolderId = safeFolderId(nextDocuments.records[recordId]?.folderId);
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         rtlSetRoot(nextDocuments.root, applied.documents.root);
@@ -3078,6 +4331,7 @@ export const planFirestoreV2OperationChanges = ({
           reason = restoredRecordId ? 'already_exists' : 'missing_record_id';
           break;
         }
+        lifecycleTombstoneId = rtlLifecycleTombstoneDocumentId('record', restoredRecordId);
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         const restoredRecord = applied.documents.records[restoredRecordId];
         if (!restoredRecord) { reason = 'restore_conflict'; break; }
@@ -3088,10 +4342,12 @@ export const planFirestoreV2OperationChanges = ({
         rtlSetRoot(nextDocuments.root, applied.documents.root);
         nextDocuments.records[restoredRecordId] = restoredRecord;
         delete nextDocuments.trash[trashEntryId];
+        const previousRecordOrder = rtlMergeOrder(targetFolder.recordOrder);
+        const restoreIndex = Number(trashEntry.originalRecordIndex || 0);
         targetFolder.recordOrder = rtlMergeOrder(
-          targetFolder.recordOrder.slice(0, Number(trashEntry.originalRecordIndex || 0)),
+          previousRecordOrder.slice(0, restoreIndex),
           [restoredRecordId],
-          targetFolder.recordOrder.slice(Number(trashEntry.originalRecordIndex || 0))
+          previousRecordOrder.slice(restoreIndex)
         );
         changed = true;
         break;
@@ -3137,7 +4393,6 @@ export const planFirestoreV2OperationChanges = ({
         break;
       case OPERATION_TYPES.FOLDER_REORDER:
       case OPERATION_TYPES.GROUP_REORDER:
-      case OPERATION_TYPES.EXPANDED_GROUPS_UPDATE:
       case OPERATION_TYPES.SETTINGS_UPDATE: {
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         const appliedRoot = applied.documents.root;
@@ -3153,12 +4408,6 @@ export const planFirestoreV2OperationChanges = ({
             nextDocuments.root.groupOrder,
             normalizedLocalState.groupOrder
           ));
-        } else if (operation.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE) {
-          appliedRoot.expandedGroups = rtlMergeOrder(
-            rtlPayloadOrder(operation, ['expandedGroups', 'groupIds', 'order', 'ids']),
-            nextDocuments.root.expandedGroups,
-            normalizedLocalState.expandedGroups
-          );
         }
         rtlSetRoot(nextDocuments.root, appliedRoot);
         changed = true;
@@ -3167,6 +4416,14 @@ export const planFirestoreV2OperationChanges = ({
       default:
         reason = 'unsupported_operation';
     }
+    if (applied && !reason && lifecycleTombstoneId) {
+      const nextTombstone = applied.documents.lifecycleTombstones?.[lifecycleTombstoneId];
+      if (nextTombstone) {
+        nextDocuments.lifecycleTombstones[lifecycleTombstoneId] = clone(nextTombstone);
+      } else {
+        delete nextDocuments.lifecycleTombstones[lifecycleTombstoneId];
+      }
+    }
     operationResults.push({
       id: operation.id || null,
       type: operation.type || null,
@@ -3183,6 +4440,9 @@ export const planFirestoreV2OperationChanges = ({
       now,
       syncMetaPatch: {lastBackgroundSyncAt: now}
     }).root;
+    if (preservedExpandedGroups !== undefined) {
+      nextDocuments.root.expandedGroups = preservedExpandedGroups;
+    }
   }
   const changes = buildFirestoreV2DocumentChangeSet(previousDocuments, nextDocuments, {
     allowDeletes: true
@@ -3200,7 +4460,7 @@ export const planFirestoreV2OperationChanges = ({
  * Counts all billable writes before a transaction reserves quota.
  */
 export const estimateFirestoreV2WriteUnits = (changes = {}, overhead = 3) => {
-  const collectionWrites = ['records', 'folders', 'trash', 'ops'].reduce((count, key) => (
+  const collectionWrites = ['records', 'folders', 'trash', 'lifecycleTombstones', 'ops'].reduce((count, key) => (
     count + Object.keys(changes?.[key]?.upserts || {}).length +
       toArray(changes?.[key]?.deleteIds).length
   ), 0);
@@ -3222,6 +4482,15 @@ const rtlStateRecordMap = (state) => {
   return records;
 };
 
+const rtlStateRecordOrders = (state) => {
+  const orders = new Map();
+  Object.entries(normalizeState(state || {}).records).forEach(([folderId, entries]) => {
+    if (VIRTUAL_FOLDER_IDS.has(folderId)) return;
+    orders.set(folderId, toArray(entries).map(getRecordId).filter(Boolean));
+  });
+  return orders;
+};
+
 const rtlComparableJson = (value) => JSON.stringify(value || {});
 
 /**
@@ -3240,6 +4509,11 @@ export const buildOperationsFromSnapshotDiff = ({
   const nextRecords = rtlStateRecordMap(next);
   const previousFolders = new Map(previous.folders.map((folder) => [folder.id, folder]));
   const nextFolders = new Map(next.folders.map((folder) => [folder.id, folder]));
+  const deletedFolderIds = new Set(
+    [...previousFolders.keys()].filter((folderId) => (
+      !RTL_PROTECTED_FOLDER_IDS.has(folderId) && !nextFolders.has(folderId)
+    ))
+  );
   const drafts = [];
   const bulkDrafts = [];
 
@@ -3271,18 +4545,29 @@ export const buildOperationsFromSnapshotDiff = ({
   });
 
   previousRecords.forEach((entry, recordId) => {
-    if (!nextRecords.has(recordId)) {
+    if (!nextRecords.has(recordId) && !deletedFolderIds.has(entry.folderId)) {
       drafts.push({type: OPERATION_TYPES.RECORD_DELETE, payload: {recordId, deletedAt: now}});
     }
   });
 
-  previousFolders.forEach((folder, folderId) => {
-    if (!RTL_PROTECTED_FOLDER_IDS.has(folderId) && !nextFolders.has(folderId)) {
-      bulkDrafts.push({
-        type: OPERATION_TYPES.FOLDER_DELETE,
-        payload: {folderId, deletedAt: now}
-      });
-    }
+  // Create prepends and move appends records, so neither operation can reproduce an arbitrary
+  // snapshot position. Emit the complete target order whenever a folder's order differs; preceding
+  // create/move/delete operations make the planner's fallback order contain only live target ids.
+  const previousRecordOrders = rtlStateRecordOrders(previous);
+  rtlStateRecordOrders(next).forEach((nextOrder, folderId) => {
+    const previousOrder = toArray(previousRecordOrders.get(folderId));
+    if (nextOrder.length === 0 || rtlComparableJson(previousOrder) === rtlComparableJson(nextOrder)) return;
+    drafts.push({
+      type: OPERATION_TYPES.RECORD_REORDER,
+      payload: {folderId, recordIds: nextOrder}
+    });
+  });
+
+  deletedFolderIds.forEach((folderId) => {
+    bulkDrafts.push({
+      type: OPERATION_TYPES.FOLDER_DELETE,
+      payload: {folderId, deletedAt: now}
+    });
   });
 
   if (rtlComparableJson(previous.folderOrder) !== rtlComparableJson(next.folderOrder)) {
@@ -3291,12 +4576,6 @@ export const buildOperationsFromSnapshotDiff = ({
   if (rtlComparableJson(previous.groupOrder) !== rtlComparableJson(next.groupOrder)) {
     drafts.push({type: OPERATION_TYPES.GROUP_REORDER, payload: {groupOrder: next.groupOrder}});
   }
-  if (rtlComparableJson(previous.expandedGroups) !== rtlComparableJson(next.expandedGroups)) {
-    drafts.push({
-      type: OPERATION_TYPES.EXPANDED_GROUPS_UPDATE,
-      payload: {expandedGroups: next.expandedGroups}
-    });
-  }
   if (rtlComparableJson(previous.settings) !== rtlComparableJson(next.settings)) {
     drafts.push({type: OPERATION_TYPES.SETTINGS_UPDATE, payload: {patch: next.settings}});
   }
@@ -3337,6 +4616,7 @@ export const buildOperationsFromSnapshotDiff = ({
 
 export default {
   RECORD_TIMELABEL_CORE_VERSION,
+  RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RTL_SYNC_PROTOCOL_VERSION,
   RTL_MAX_OPERATIONS_PER_REQUEST,
   RTL_MAX_REQUEST_BYTES,
@@ -3346,7 +4626,10 @@ export default {
   RECORD_TIMELABEL_SYNC_MODES,
   RECORD_TIMELABEL_CLOUD_SCHEMAS,
   FIRESTORE_V2_SETTINGS_DOC_ID,
+  RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS,
   normalizeState,
+  normalizeRecordTimeLabelDomainState,
+  migrateRecordTimeLabelExpandedGroups,
   getActiveTrashEntries,
   hasMeaningfulRecordTimeLabelCloudState,
   buildRecordTimeLabelContentFingerprint,
@@ -3373,12 +4656,15 @@ export default {
   extendFirestoreV2OperationReadPlanWithTrash,
   planFirestoreV2OperationChanges,
   estimateFirestoreV2WriteUnits,
+  normalizeRecordTimeLabelOperationResults,
+  normalizeRecordTimeLabelEnvelopeResponse,
   buildOperationsFromSnapshotDiff,
   flushPendingOperations,
   mergeRemoteStateIntoLocal,
   applyOperation,
   applyRecordTimeLabelOperation,
   createOperation,
+  createRecordTimeLabelSyncEngine,
   createSyncEngine,
   createRecordTimeLabelController
 };