@recordtimelabel/core 0.1.1 → 0.1.3

package/README.md

@@ -11,25 +11,44 @@ Current consumers:
 - `D:\Programming\RecordTimeLabel`
 - `D:\Programming\YouTwitchDownloader`
 
-During local development both apps consume it with:
+During local development an app can consume a sibling checkout with:
 
 ```json
 "@recordtimelabel/core": "file:../recordtimelabel-core"
 ```
 
-For release builds, move this dependency to a git tag, npm package, or private registry version so builds do not depend on a sibling folder path.
+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 current release candidate is:
+
+```json
+"@recordtimelabel/core": "0.1.2"
+```
 
 ## Public API
 
 - `normalizeState(input)`
 - `normalizeRecords(records, options)`
-- `mergeLocalRemote({ localState, remoteState, pendingOps, clientId, now })`
-- `applyOperation(state, operation)`
-- `createSyncEngine({ storageAdapter, cloudAdapter, clientId, clock, logger })`
-- `buildRecordTimeLabelSyncPayload({ data, previousCloudData, pendingOps, syncMode, clientId, now })`
-- `RECORD_TIMELABEL_SYNC_MODES`
-- `createOperation(type, payload, options)`
-- `OPERATION_TYPES`
+- `mergeLocalRemote({ localState, remoteState, pendingOps, clientId, now })`
+- `applyOperation(state, operation)`
+- `applyRecordTimeLabelOperation(state, operation)`
+- `createSyncEngine({ storageAdapter, cloudAdapter, clientId, clock, logger })`
+- `createRecordTimeLabelController({ storageAdapter, cloudAdapter, clientId, settingKeys, clock, logger })`
+- `buildRecordTimeLabelSyncPayload({ data, previousCloudData, pendingOps, syncMode, clientId, now })`
+- `buildSyncPayloadWithOperations({ data, previousCloudData, pendingOps, syncMode, clientId, now })`
+- `flushPendingOperations({ operations, storageAdapter, cloudAdapter, clientId, now })`
+- `mergeRemoteStateIntoLocal({ localData, remoteData, pendingOps, settingKeys, clientId, now })`
+- `buildLocalStateFromStorage(data, options)`
+- `buildStoragePatchFromState(state, options)`
+- `buildFirestoreV1UserPatch(state, options)`
+- `buildFirestoreV2LogicalPaths(userId)`
+- `buildFirestoreV2DocumentsFromState(state, options)`
+- `buildStateFromFirestoreV2Documents(documents, options)`
+- `hasMeaningfulRecordTimeLabelCloudState(data, options)`
+- `buildRecordTimeLabelContentFingerprint(data)`
+- `buildMigratedRecordTimeLabelV2State(legacyState, options)`
+- `RECORD_TIMELABEL_CLOUD_SCHEMAS`
+- `RECORD_TIMELABEL_SYNC_MODES`
+- `createOperation(type, payload, options)`
+- `OPERATION_TYPES`
 
 ## Firestore v1 Compatibility
 
@@ -48,7 +67,18 @@ The core also normalizes and preserves these compatibility metadata fields:
 - `deletedRecordTombstones`
 - `deletedFolderTombstones`
 
-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.
+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.
+
+## Firestore v2 Preparation
+
+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:
+
+- root document `users/{uid}/recordTimeLabel/main`: settings, order arrays, tombstones, and sync metadata
+- `users/{uid}/recordTimeLabel/main/records/{recordId}`: flattened per-record documents with `folderId`
+- `users/{uid}/recordTimeLabel/main/folders/{folderId}`: per-folder documents
+- `users/{uid}/recordTimeLabel/main/ops/{opId}`: pending operation documents
+
+These helpers do not import Firebase and do not perform network writes.
 
 ## Test
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",

package/src/index.js

@@ -5,31 +5,40 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.1.1';
-
-export const OPERATION_TYPES = Object.freeze({
-  RECORD_CREATE: 'record.create',
-  RECORD_UPDATE: 'record.update',
-  RECORD_MOVE: 'record.move',
-  RECORD_DELETE: 'record.delete',
-  FOLDER_CREATE: 'folder.create',
-  FOLDER_UPDATE: 'folder.update',
-  FOLDER_DELETE: 'folder.delete',
-  FOLDER_REORDER: 'folder.reorder',
-  GROUP_REORDER: 'group.reorder',
-  SETTINGS_UPDATE: 'settings.update'
-});
-
-export const RECORD_TIMELABEL_SYNC_MODES = Object.freeze({
-  FULL: 'full',
-  MERGE: 'merge'
-});
-
-const toArray = (value) => (Array.isArray(value) ? value : []);
-const clone = (value) => {
-  if (value === undefined || value === null) return value;
-  return JSON.parse(JSON.stringify(value));
-};
+export const RECORD_TIMELABEL_CORE_VERSION = '0.1.2';
+
+export const OPERATION_TYPES = Object.freeze({
+  RECORD_CREATE: 'record.create',
+  RECORD_UPDATE: 'record.update',
+  RECORD_MOVE: 'record.move',
+  RECORD_DELETE: 'record.delete',
+  RECORD_REORDER: 'record.reorder',
+  FOLDER_CREATE: 'folder.create',
+  FOLDER_UPDATE: 'folder.update',
+  FOLDER_DELETE: 'folder.delete',
+  FOLDER_REORDER: 'folder.reorder',
+  GROUP_REORDER: 'group.reorder',
+  EXPANDED_GROUPS_UPDATE: 'expandedGroups.update',
+  SETTINGS_UPDATE: 'settings.update'
+});
+
+export const RECORD_TIMELABEL_SYNC_MODES = Object.freeze({
+  FULL: 'full',
+  MERGE: 'merge'
+});
+
+export const RECORD_TIMELABEL_CLOUD_SCHEMAS = Object.freeze({
+  V1: 'v1',
+  V2: 'v2'
+});
+
+export const FIRESTORE_V2_SETTINGS_DOC_ID = 'main';
+
+const toArray = (value) => (Array.isArray(value) ? value : []);
+const clone = (value) => {
+  if (value === undefined || value === null) return value;
+  return JSON.parse(JSON.stringify(value));
+};
 
 const toFiniteTimestamp = (value) => {
   if (typeof value === 'number') {
@@ -97,9 +106,23 @@ const safeFolderId = (folderId) => {
   return normalized;
 };
 
-const normalizeOrder = (value) => Array.from(new Set(
-  toArray(value).map(normalizeId).filter(Boolean)
-));
+const normalizeOrder = (value) => Array.from(new Set(
+  toArray(value).map(normalizeId).filter(Boolean)
+));
+
+const normalizeIdList = (ids) => {
+  const seen = new Set();
+  const result = [];
+  toArray(ids).forEach((id) => {
+    const normalized = normalizeId(id);
+    if (!normalized || seen.has(normalized)) return;
+    seen.add(normalized);
+    result.push(normalized);
+  });
+  return result;
+};
+
+const getRecordId = (record) => normalizeId(record?.id || record?.recordId);
 
 const normalizeTombstones = (value) => {
   if (!value) return {};
@@ -187,11 +210,12 @@ export const mergeRecords = (left, right) => {
   return merged;
 };
 
-export const normalizeRecords = (records = {}, options = {}) => {
-  const source = records && typeof records === 'object' ? records : {};
-  const tombstones = normalizeTombstones(options.deletedRecordTombstones);
-  const normalized = { all: [], [DEFAULT_FOLDER_ID]: [] };
-  const placements = new Map();
+export const normalizeRecords = (records = {}, options = {}) => {
+  const source = records && typeof records === 'object' ? records : {};
+  const tombstones = normalizeTombstones(options.deletedRecordTombstones);
+  const folderTombstones = normalizeTombstones(options.deletedFolderTombstones);
+  const normalized = { all: [], [DEFAULT_FOLDER_ID]: [] };
+  const placements = new Map();
 
   Object.entries(source).forEach(([folderId, folderRecords]) => {
     const safeList = toArray(folderRecords);
@@ -199,23 +223,28 @@ export const normalizeRecords = (records = {}, options = {}) => {
       if (!record || typeof record !== 'object') return;
       const id = normalizeId(record.id) || normalizeId(record.recordId);
       if (!id) return;
-
-      const targetFolderId = resolveRecordFolderId(folderId, record);
-      if (!normalized[targetFolderId]) normalized[targetFolderId] = [];
-
-      const normalizedRecord = {
-        ...record,
+
+      const targetFolderId = resolveRecordFolderId(folderId, record);
+
+      const normalizedRecord = {
+        ...record,
         id
       };
       delete normalizedRecord.folderId;
       delete normalizedRecord.sortIndex;
-
-      const tombstone = tombstones[id];
-      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= getRecordTime(normalizedRecord)) {
-        return;
-      }
-
-      const existing = placements.get(id);
+
+      const tombstone = tombstones[id];
+      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= getRecordTime(normalizedRecord)) {
+        return;
+      }
+      const folderTombstone = folderTombstones[targetFolderId];
+      if (folderTombstone && toFiniteTimestamp(folderTombstone.deletedAt) >= getRecordTime(normalizedRecord)) {
+        return;
+      }
+
+      if (!normalized[targetFolderId]) normalized[targetFolderId] = [];
+
+      const existing = placements.get(id);
       if (!existing) {
         normalized[targetFolderId].push(normalizedRecord);
         placements.set(id, {
@@ -345,19 +374,19 @@ const mergeOrderWithLocalIds = (remoteOrder = [], localOrder = [], allowedIds =
   return merged;
 };
 
-export const normalizeState = (input = {}) => {
-  const deletedRecordTombstones = normalizeTombstones(input.deletedRecordTombstones);
-  const deletedFolderTombstones = normalizeTombstones(input.deletedFolderTombstones);
-  const folders = ensureFolders(input.folders).filter((folder) => {
+export const normalizeState = (input = {}) => {
+  const deletedRecordTombstones = normalizeTombstones(input.deletedRecordTombstones);
+  const deletedFolderTombstones = normalizeTombstones(input.deletedFolderTombstones);
+  const folders = ensureFolders(input.folders).filter((folder) => {
     const tombstone = deletedFolderTombstones[folder.id];
     if (!tombstone) return true;
     const folderTime = toFiniteTimestamp(folder.updatedAt || folder.createdAt);
     return folderTime > toFiniteTimestamp(tombstone.deletedAt);
   });
-  const records = ensureRecordFolders(
-    normalizeRecords(input.records, { deletedRecordTombstones }),
-    folders
-  );
+  const records = ensureRecordFolders(
+    normalizeRecords(input.records, { deletedRecordTombstones, deletedFolderTombstones }),
+    folders
+  );
 
   return {
     folders,
@@ -372,11 +401,61 @@ export const normalizeState = (input = {}) => {
     },
     deletedRecordTombstones,
     deletedFolderTombstones,
-    lastModified: toFiniteTimestamp(input.lastModified || input.updatedAt || input.lastUpdated)
-  };
-};
-
-const removeRecordById = (records, recordId) => {
+    lastModified: toFiniteTimestamp(input.lastModified || input.updatedAt || input.lastUpdated)
+  };
+};
+
+export const hasMeaningfulRecordTimeLabelCloudState = (input = {}, options = {}) => {
+  const state = normalizeState(input || {});
+  const defaultFolderIds = new Set(options.defaultFolderIds || ['all', 'uncategorized']);
+  const hasCustomFolder = state.folders.some((folder) => (
+    folder?.id && !defaultFolderIds.has(folder.id)
+  ));
+  const hasRecords = Object.values(state.records || {}).some((records) => (
+    Array.isArray(records) && records.length > 0
+  ));
+  const hasNonDefaultGroupOrder = state.groupOrder.some((id) => (
+    typeof id === 'string' && id.trim() && !defaultFolderIds.has(id.trim())
+  ));
+
+  return hasCustomFolder ||
+    hasRecords ||
+    Object.keys(state.settings || {}).length > 0 ||
+    Object.keys(state.deletedRecordTombstones || {}).length > 0 ||
+    Object.keys(state.deletedFolderTombstones || {}).length > 0 ||
+    hasNonDefaultGroupOrder ||
+    state.folderOrder.length > 0 ||
+    state.expandedGroups.length > 0;
+};
+
+export const buildRecordTimeLabelContentFingerprint = (input = {}) => {
+  const state = normalizeState(input || {});
+  return JSON.stringify({
+    folders: state.folders,
+    records: state.records,
+    settings: state.settings,
+    groupOrder: state.groupOrder,
+    folderOrder: state.folderOrder,
+    expandedGroups: state.expandedGroups,
+    deletedRecordTombstones: state.deletedRecordTombstones,
+    deletedFolderTombstones: state.deletedFolderTombstones
+  });
+};
+
+export const buildMigratedRecordTimeLabelV2State = (legacyState = {}, options = {}) => {
+  const migratedAt = toFiniteTimestamp(options.migratedAt || options.now || Date.now()) || Date.now();
+  return normalizeState({
+    ...(legacyState || {}),
+    rtlSyncMeta: {
+      ...(legacyState?.rtlSyncMeta && typeof legacyState.rtlSyncMeta === 'object' ? legacyState.rtlSyncMeta : {}),
+      schemaVersion: 2,
+      lastMigratedFromV1At: migratedAt
+    },
+    lastModified: legacyState?.lastModified || migratedAt
+  });
+};
+
+const removeRecordById = (records, recordId) => {
   const nextRecords = {};
   Object.entries(records || {}).forEach(([folderId, folderRecords]) => {
     nextRecords[folderId] = toArray(folderRecords).filter((record) => record?.id !== recordId);
@@ -384,15 +463,56 @@ const removeRecordById = (records, recordId) => {
   return nextRecords;
 };
 
-const findRecordEntry = (records, recordId) => {
-  for (const [folderId, folderRecords] of Object.entries(records || {})) {
-    const index = toArray(folderRecords).findIndex((record) => record?.id === recordId);
+const findRecordEntry = (records, recordId) => {
+  for (const [folderId, folderRecords] of Object.entries(records || {})) {
+    const index = toArray(folderRecords).findIndex((record) => record?.id === recordId);
     if (index !== -1) {
       return { folderId, index, record: folderRecords[index] };
     }
   }
-  return null;
-};
+  return null;
+};
+
+const orderRecordsByReference = (records, referenceRecords) => {
+  const targetRecords = toArray(records);
+  const referenceOrder = normalizeIdList(toArray(referenceRecords).map((record) => getRecordId(record)));
+  if (targetRecords.length < 2 || referenceOrder.length < 2) {
+    return targetRecords;
+  }
+
+  const recordsById = new Map();
+  targetRecords.forEach((record) => {
+    const recordId = getRecordId(record);
+    if (recordId && !recordsById.has(recordId)) {
+      recordsById.set(recordId, record);
+    }
+  });
+
+  const seen = new Set();
+  const orderedRecords = [];
+  referenceOrder.forEach((recordId) => {
+    const record = recordsById.get(recordId);
+    if (!record || seen.has(recordId)) return;
+    seen.add(recordId);
+    orderedRecords.push(record);
+  });
+  targetRecords.forEach((record) => {
+    const recordId = getRecordId(record);
+    if (!recordId || seen.has(recordId)) return;
+    seen.add(recordId);
+    orderedRecords.push(record);
+  });
+
+  return orderedRecords;
+};
+
+export const preserveRecordOrderFromLocal = (records = {}, localRecords = {}) => {
+  const result = {};
+  Object.keys(records || {}).forEach((folderId) => {
+    result[folderId] = orderRecordsByReference(records?.[folderId], localRecords?.[folderId]);
+  });
+  return result;
+};
 
 export const createOperation = (type, payload = {}, options = {}) => ({
   id: options.id || `${type}:${options.clientId || 'client'}:${options.now || Date.now()}:${Math.random().toString(36).slice(2, 10)}`,
@@ -454,9 +574,9 @@ export const applyOperation = (state = {}, operation = {}) => {
       break;
     }
 
-    case OPERATION_TYPES.RECORD_MOVE: {
-      const recordId = normalizeId(payload.recordId || payload.id || payload.record?.id);
-      const targetFolderId = safeFolderId(payload.targetFolderId || payload.folderId);
+    case OPERATION_TYPES.RECORD_MOVE: {
+      const recordId = normalizeId(payload.recordId || payload.id || payload.record?.id);
+      const targetFolderId = safeFolderId(payload.targetFolderId || payload.folderId);
       if (!recordId) return normalized;
       const entry = findRecordEntry(nextState.records, recordId);
       if (!entry) return normalized;
@@ -471,8 +591,56 @@ export const applyOperation = (state = {}, operation = {}) => {
         ...toArray(nextState.records[targetFolderId]),
         movedRecord
       ];
-      break;
-    }
+      break;
+    }
+
+    case OPERATION_TYPES.RECORD_REORDER: {
+      const folderId = safeFolderId(payload.folderId);
+      const existingFolderRecords = toArray(nextState.records?.[folderId]);
+      const payloadRecords = toArray(payload.records);
+      const recordsById = new Map();
+
+      existingFolderRecords.forEach((record) => {
+        const recordId = getRecordId(record);
+        if (recordId && !recordsById.has(recordId)) {
+          recordsById.set(recordId, { ...record, id: recordId });
+        }
+      });
+      payloadRecords.forEach((record) => {
+        const recordId = getRecordId(record);
+        if (!recordId) return;
+        recordsById.set(recordId, {
+          ...(recordsById.get(recordId) || {}),
+          ...record,
+          id: recordId
+        });
+      });
+
+      const orderedIds = normalizeIdList(
+        Array.isArray(payload.recordIds)
+          ? payload.recordIds
+          : payloadRecords.map((record) => getRecordId(record))
+      );
+      if (orderedIds.length === 0) return normalized;
+
+      const seen = new Set();
+      const reorderedRecords = [];
+      orderedIds.forEach((recordId) => {
+        const record = recordsById.get(recordId);
+        if (!record || seen.has(recordId)) return;
+        seen.add(recordId);
+        reorderedRecords.push(record);
+      });
+      existingFolderRecords.forEach((record) => {
+        const recordId = getRecordId(record);
+        if (!recordId || seen.has(recordId)) return;
+        seen.add(recordId);
+        reorderedRecords.push(record);
+      });
+
+      nextState.records[folderId] = reorderedRecords;
+      break;
+    }
 
     case OPERATION_TYPES.RECORD_DELETE: {
       const recordId = normalizeId(payload.recordId || payload.id);
@@ -538,14 +706,18 @@ export const applyOperation = (state = {}, operation = {}) => {
       nextState.folderOrder = normalizeOrder(payload.folderOrder || payload.order);
       break;
 
-    case OPERATION_TYPES.GROUP_REORDER:
-      nextState.groupOrder = normalizeOrder(payload.groupOrder || payload.order);
-      break;
-
-    case OPERATION_TYPES.SETTINGS_UPDATE:
-      nextState.settings = {
-        ...nextState.settings,
-        ...(payload.patch || payload.settings || {})
+    case OPERATION_TYPES.GROUP_REORDER:
+      nextState.groupOrder = normalizeOrder(payload.groupOrder || payload.order);
+      break;
+
+    case OPERATION_TYPES.EXPANDED_GROUPS_UPDATE:
+      nextState.expandedGroups = normalizeOrder(payload.expandedGroups || payload.groupIds || payload.order || payload.ids);
+      break;
+
+    case OPERATION_TYPES.SETTINGS_UPDATE:
+      nextState.settings = {
+        ...nextState.settings,
+        ...(payload.patch || payload.settings || {})
       };
       break;
 
@@ -557,12 +729,15 @@ export const applyOperation = (state = {}, operation = {}) => {
   nextState.rtlSyncMeta = {
     ...nextState.rtlSyncMeta,
     lastOperationId: operation.id || nextState.rtlSyncMeta.lastOperationId || null,
-    lastClientId: operation.clientId || nextState.rtlSyncMeta.lastClientId || null,
+    lastOperationType: operation.type || nextState.rtlSyncMeta.lastOperationType || null,
+    lastClientId: operation.clientId || nextState.rtlSyncMeta.lastClientId || null,
     lastOperationAt: operationTime
   };
-
-  return normalizeState(nextState);
-};
+
+  return normalizeState(nextState);
+};
+
+export const applyRecordTimeLabelOperation = (state = {}, operation = {}) => applyOperation(state, operation);
 
 export const mergeLocalRemote = ({
   localState = {},
@@ -586,12 +761,12 @@ export const mergeLocalRemote = ({
 
   let mergedState = normalizeState({
     ...remote,
-    folders,
-    records: { ...remote.records },
-    groupOrder: mergeOrderWithLocalIds(remote.groupOrder, local.groupOrder, folderIds),
-    folderOrder: mergeOrderWithLocalIds(remote.folderOrder, local.folderOrder, folderIds),
-    expandedGroups: mergeOrderWithLocalIds(remote.expandedGroups, local.expandedGroups, folderIds),
-    settings: { ...remote.settings, ...local.settings },
+    folders,
+    records: { ...remote.records },
+    groupOrder: mergeOrderArrays(null, remote.groupOrder, local.groupOrder),
+    folderOrder: mergeOrderWithLocalIds(remote.folderOrder, local.folderOrder, folderIds),
+    expandedGroups: mergeOrderArrays(null, remote.expandedGroups, local.expandedGroups),
+    settings: { ...remote.settings, ...local.settings },
     deletedRecordTombstones,
     deletedFolderTombstones,
     rtlSyncMeta: {
@@ -705,8 +880,8 @@ export const buildDeletionTombstones = ({
   };
 };
 
-const removeRecordSyncFlags = (records = {}) => Object.fromEntries(
-  Object.entries(normalizeRecords(records || {})).map(([folderId, recordList]) => [
+const removeRecordSyncFlags = (records = {}) => Object.fromEntries(
+  Object.entries(normalizeRecords(records || {})).map(([folderId, recordList]) => [
     folderId,
     toArray(recordList).map((record) => {
       const cleanRecord = { ...record };
@@ -714,10 +889,354 @@ const removeRecordSyncFlags = (records = {}) => Object.fromEntries(
       delete cleanRecord.syncAttempts;
       return cleanRecord;
     })
-  ])
-);
-
-const buildSyncStateInput = (data = {}, operationTime) => ({
+  ])
+);
+
+export const buildSettingsFromStorage = (data = {}, options = {}) => {
+  const settingKeys = toArray(options.settingKeys);
+  const settings = data.settings && typeof data.settings === 'object'
+    ? { ...data.settings }
+    : {};
+
+  settingKeys.forEach((key) => {
+    if (data[key] !== undefined) {
+      settings[key] = data[key];
+    }
+  });
+
+  return settings;
+};
+
+const normalizeGroupOrderForOption = (order, normalizer) => (
+  typeof normalizer === 'function' ? normalizer(order) : normalizeOrder(order)
+);
+
+export const buildLocalStateFromStorage = (data = {}, options = {}) => normalizeState({
+  folders: data.folders || [],
+  records: data.records || {},
+  groupOrder: normalizeGroupOrderForOption(data.groupOrder, options.groupOrderNormalizer),
+  folderOrder: data.folderOrder || [],
+  expandedGroups: data.expandedGroups || [],
+  settings: buildSettingsFromStorage(data, options),
+  rtlSyncMeta: data.rtlSyncMeta || {},
+  deletedRecordTombstones: data.deletedRecordTombstones || {},
+  deletedFolderTombstones: data.deletedFolderTombstones || {},
+  lastModified: data.lastModified || data.updatedAt || 0
+});
+
+const resolveNow = (now) => (typeof now === 'function' ? now() : (now || Date.now()));
+
+export const buildStoragePatchFromState = (state = {}, options = {}) => {
+  const normalized = normalizeState(state || {});
+  const settings = normalized.settings || {};
+  const storagePatch = {
+    folders: normalized.folders,
+    records: normalized.records,
+    groupOrder: normalizeGroupOrderForOption(normalized.groupOrder, options.groupOrderNormalizer),
+    folderOrder: normalized.folderOrder,
+    expandedGroups: normalized.expandedGroups,
+    settings,
+    rtlSyncMeta: normalized.rtlSyncMeta,
+    deletedRecordTombstones: normalized.deletedRecordTombstones,
+    deletedFolderTombstones: normalized.deletedFolderTombstones,
+    lastModified: normalized.lastModified || resolveNow(options.now)
+  };
+
+  toArray(options.settingKeys).forEach((key) => {
+    if (settings[key] !== undefined) {
+      storagePatch[key] = settings[key];
+    }
+  });
+
+  return storagePatch;
+};
+
+export const buildFirestoreV1UserPatch = (state = {}, options = {}) => {
+  const normalized = normalizeState(state || {});
+  return {
+    folders: normalized.folders,
+    records: removeRecordSyncFlags(normalized.records || {}),
+    groupOrder: normalizeGroupOrderForOption(normalized.groupOrder, options.groupOrderNormalizer),
+    folderOrder: normalized.folderOrder,
+    expandedGroups: normalized.expandedGroups,
+    settings: normalized.settings || {},
+    rtlSyncMeta: {
+      ...(normalized.rtlSyncMeta || {}),
+      schemaVersion: 1,
+      ...(options.syncMetaPatch || {})
+    },
+    deletedRecordTombstones: normalized.deletedRecordTombstones || {},
+    deletedFolderTombstones: normalized.deletedFolderTombstones || {},
+    lastModified: normalized.lastModified || resolveNow(options.now)
+  };
+};
+
+export const buildFirestoreV2LogicalPaths = (userId = '{uid}') => {
+  const uid = String(userId || '{uid}');
+  const root = `users/${uid}/recordTimeLabel/${FIRESTORE_V2_SETTINGS_DOC_ID}`;
+  return {
+    root,
+    records: `${root}/records`,
+    folders: `${root}/folders`,
+    settings: root,
+    ops: `${root}/ops`
+  };
+};
+
+const mapValuesArray = (value = {}) => {
+  if (Array.isArray(value)) return value;
+  if (!value || typeof value !== 'object') return [];
+  return Object.values(value);
+};
+
+const cleanV2RecordDocument = (record = {}, folderId, now) => {
+  const recordId = normalizeId(record.id);
+  if (!recordId) return null;
+  const cleanRecord = { ...record, id: recordId, folderId: safeFolderId(folderId) };
+  delete cleanRecord.pendingSync;
+  delete cleanRecord.syncAttempts;
+  return {
+    ...cleanRecord,
+    updatedAt: cleanRecord.updatedAt || cleanRecord.createdAt || now,
+    schemaVersion: 2
+  };
+};
+
+const cleanV2FolderDocument = (folder = {}, now) => {
+  const folderId = normalizeId(folder.id);
+  if (!folderId) return null;
+  return {
+    ...folder,
+    id: folderId,
+    updatedAt: folder.updatedAt || folder.createdAt || now,
+    schemaVersion: 2
+  };
+};
+
+const cleanV2OperationDocument = (operation = {}, now) => {
+  const operationId = normalizeId(operation.id);
+  if (!operationId || !operation.type) return null;
+  return {
+    ...operation,
+    id: operationId,
+    createdAt: operation.createdAt || now,
+    schemaVersion: 2
+  };
+};
+
+export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) => {
+  const normalized = normalizeState(state || {});
+  const now = resolveNow(options.now);
+  const records = {};
+  Object.entries(removeRecordSyncFlags(normalized.records || {})).forEach(([folderId, recordList]) => {
+    toArray(recordList).forEach((record) => {
+      const recordDoc = cleanV2RecordDocument(record, folderId, now);
+      if (recordDoc) records[recordDoc.id] = recordDoc;
+    });
+  });
+
+  const folders = {};
+  toArray(normalized.folders).forEach((folder) => {
+    const folderDoc = cleanV2FolderDocument(folder, now);
+    if (folderDoc) folders[folderDoc.id] = folderDoc;
+  });
+
+  const ops = {};
+  toArray(options.pendingOps || state.pendingOps).forEach((operation) => {
+    const operationDoc = cleanV2OperationDocument(operation, now);
+    if (operationDoc) ops[operationDoc.id] = operationDoc;
+  });
+
+  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,
+      ...(options.syncMetaPatch || {})
+    },
+    deletedRecordTombstones: normalized.deletedRecordTombstones || {},
+    deletedFolderTombstones: normalized.deletedFolderTombstones || {},
+    lastModified: normalized.lastModified || now
+  };
+
+  return {
+    schemaVersion: 2,
+    root,
+    records,
+    folders,
+    ops
+  };
+};
+
+const removeV2Metadata = (data = {}) => {
+  const { schemaVersion, folderId, ...rest } = data || {};
+  return rest;
+};
+
+export const buildStateFromFirestoreV2Documents = (documents = {}, options = {}) => {
+  const rootDoc = documents?.root ||
+    documents?.settings?.[FIRESTORE_V2_SETTINGS_DOC_ID] ||
+    documents?.settings ||
+    {};
+  const records = {};
+  mapValuesArray(documents?.records).forEach((recordDoc) => {
+    const recordId = normalizeId(recordDoc?.id);
+    if (!recordId) return;
+    const folderId = safeFolderId(recordDoc.folderId);
+    records[folderId] = [
+      ...toArray(records[folderId]),
+      { ...removeV2Metadata(recordDoc), id: recordId }
+    ];
+  });
+
+  const folders = mapValuesArray(documents?.folders)
+    .map((folderDoc) => {
+      const folderId = normalizeId(folderDoc?.id);
+      if (!folderId) return null;
+      const { schemaVersion, ...folder } = folderDoc;
+      return { ...folder, id: folderId };
+    })
+    .filter(Boolean);
+
+  const pendingOps = mapValuesArray(documents?.ops)
+    .map((operationDoc) => {
+      const operationId = normalizeId(operationDoc?.id);
+      if (!operationId || !operationDoc?.type) return null;
+      const { schemaVersion, ...operation } = operationDoc;
+      return { ...operation, id: operationId };
+    })
+    .filter(Boolean);
+
+  const state = normalizeState({
+    folders,
+    records,
+    settings: rootDoc.settings || {},
+    groupOrder: normalizeGroupOrderForOption(rootDoc.groupOrder, options.groupOrderNormalizer),
+    folderOrder: rootDoc.folderOrder || [],
+    expandedGroups: rootDoc.expandedGroups || [],
+    rtlSyncMeta: rootDoc.rtlSyncMeta || {},
+    deletedRecordTombstones: rootDoc.deletedRecordTombstones || {},
+    deletedFolderTombstones: rootDoc.deletedFolderTombstones || {},
+    lastModified: rootDoc.lastModified || 0
+  });
+
+  return { state, pendingOps };
+};
+
+const mergeOrderArrays = (normalizer, ...orders) => {
+  const seen = new Set();
+  const result = [];
+  orders.forEach((order) => {
+    normalizeGroupOrderForOption(order, normalizer).forEach((id) => {
+      if (seen.has(id)) return;
+      seen.add(id);
+      result.push(id);
+    });
+  });
+  return result;
+};
+
+const getLatestPendingOrder = (pendingOps = [], operationType, payloadKeys = []) => {
+  const operations = toArray(pendingOps);
+  for (let index = operations.length - 1; index >= 0; index -= 1) {
+    const operation = operations[index];
+    if (operation?.type !== operationType) continue;
+    const payload = operation.payload || {};
+    const order = payloadKeys.map((key) => payload[key]).find(Array.isArray);
+    if (Array.isArray(order)) return order;
+  }
+  return null;
+};
+
+const resolvePayloadOrder = ({
+  data,
+  previousCloudData,
+  payloadState,
+  pendingOps,
+  operationType,
+  payloadKeys,
+  stateKey,
+  normalizer
+} = {}) => {
+  const pendingOrder = getLatestPendingOrder(pendingOps, operationType, payloadKeys);
+  if (pendingOrder) {
+    return mergeOrderArrays(normalizer, pendingOrder, previousCloudData?.[stateKey]);
+  }
+
+  const localOrder = normalizeGroupOrderForOption(data?.[stateKey], normalizer);
+  const cloudOrder = normalizeGroupOrderForOption(previousCloudData?.[stateKey], normalizer);
+  const payloadOrder = normalizeGroupOrderForOption(payloadState?.[stateKey], normalizer);
+  return mergeOrderArrays(normalizer, localOrder, cloudOrder, payloadOrder);
+};
+
+const getLastLocalOperationType = (data = {}) => String(
+  data?.rtlSyncMeta?.lastOperationType ||
+  data?.syncMeta?.lastLocalOperationType ||
+  ''
+);
+
+const getLastLocalOperationAt = (data = {}) => toFiniteTimestamp(
+  data?.rtlSyncMeta?.lastOperationAt ||
+  data?.rtlSyncMeta?.lastLocalOperationAt ||
+  data?.syncMeta?.lastLocalOperationAt ||
+  data?.lastModified
+);
+
+const getLastRemoteOperationAt = (data = {}) => toFiniteTimestamp(
+  data?.rtlSyncMeta?.lastOperationAt ||
+  data?.rtlSyncMeta?.lastBackgroundSyncAt ||
+  data?.lastModified
+);
+
+const hasRecentLocalOperation = (localData = {}, remoteData = {}, operationType) => {
+  const lastOperationId = String(localData?.rtlSyncMeta?.lastOperationId || '');
+  const lastOperationType = getLastLocalOperationType(localData);
+  if (!lastOperationId.startsWith(`${operationType}:`) && lastOperationType !== operationType) {
+    return false;
+  }
+
+  const localOperationAt = getLastLocalOperationAt(localData);
+  const remoteOperationAt = getLastRemoteOperationAt(remoteData);
+  return !localOperationAt || !remoteOperationAt || localOperationAt >= remoteOperationAt;
+};
+
+const shouldPreferRecentLocalOrder = (localData = {}, remoteData = {}, operationType) => {
+  if (hasRecentLocalOperation(localData, remoteData, operationType)) {
+    return true;
+  }
+
+  const localOperationAt = getLastLocalOperationAt(localData);
+  const remoteOperationAt = getLastRemoteOperationAt(remoteData);
+  return Boolean(localOperationAt) && (!remoteOperationAt || localOperationAt >= remoteOperationAt);
+};
+
+const resolveMergedOrder = ({
+  localData = {},
+  remoteData = {},
+  pendingOps = [],
+  operationType,
+  payloadKeys,
+  stateKey,
+  normalizer
+} = {}) => {
+  const pendingOrder = getLatestPendingOrder(pendingOps, operationType, payloadKeys);
+  if (pendingOrder) {
+    return mergeOrderArrays(normalizer, pendingOrder, remoteData?.[stateKey], localData?.[stateKey]);
+  }
+
+  if (shouldPreferRecentLocalOrder(localData, remoteData, operationType)) {
+    return mergeOrderArrays(normalizer, localData?.[stateKey], remoteData?.[stateKey]);
+  }
+
+  return mergeOrderArrays(normalizer, remoteData?.[stateKey], localData?.[stateKey]);
+};
+
+const buildSyncStateInput = (data = {}, operationTime) => ({
   folders: data?.folders || [],
   records: data?.records || {},
   settings: data?.settings || {},
@@ -730,7 +1249,7 @@ const buildSyncStateInput = (data = {}, operationTime) => ({
   lastModified: operationTime
 });
 
-export const buildRecordTimeLabelSyncPayload = ({
+export const buildRecordTimeLabelSyncPayload = ({
   data,
   previousCloudData,
   pendingOps = [],
@@ -766,7 +1285,390 @@ export const buildRecordTimeLabelSyncPayload = ({
     deletedFolderTombstones: deletionTombstones.deletedFolderTombstones,
     lastModified: operationTime
   });
-};
+};
+
+export const buildSyncPayloadWithOperations = ({
+  data,
+  previousCloudData,
+  pendingOps = [],
+  syncMode = RECORD_TIMELABEL_SYNC_MODES.FULL,
+  clientId = 'recordtimelabel-client',
+  now = Date.now(),
+  groupOrderNormalizer
+} = {}) => {
+  const operations = toArray(pendingOps);
+  let payloadState = buildRecordTimeLabelSyncPayload({
+    data,
+    previousCloudData,
+    pendingOps: [],
+    syncMode,
+    clientId,
+    now
+  });
+
+  operations.forEach((operation) => {
+    payloadState = applyRecordTimeLabelOperation(payloadState, operation);
+  });
+
+  const hasPendingRecordReorder = operations.some((operation) => (
+    operation?.type === OPERATION_TYPES.RECORD_REORDER
+  ));
+  const recordsForPayload = hasPendingRecordReorder
+    ? payloadState.records || {}
+    : preserveRecordOrderFromLocal(payloadState.records || {}, data?.records || {});
+
+  return normalizeState({
+    ...payloadState,
+    groupOrder: resolvePayloadOrder({
+      data,
+      previousCloudData,
+      payloadState,
+      pendingOps: operations,
+      operationType: OPERATION_TYPES.GROUP_REORDER,
+      payloadKeys: ['groupOrder', 'order'],
+      stateKey: 'groupOrder',
+      normalizer: groupOrderNormalizer
+    }),
+    folderOrder: resolvePayloadOrder({
+      data,
+      previousCloudData,
+      payloadState,
+      pendingOps: operations,
+      operationType: OPERATION_TYPES.FOLDER_REORDER,
+      payloadKeys: ['folderOrder', 'order'],
+      stateKey: 'folderOrder'
+    }),
+    expandedGroups: resolvePayloadOrder({
+      data,
+      previousCloudData,
+      payloadState,
+      pendingOps: operations,
+      operationType: OPERATION_TYPES.EXPANDED_GROUPS_UPDATE,
+      payloadKeys: ['expandedGroups', 'groupIds', 'order', 'ids'],
+      stateKey: 'expandedGroups'
+    }),
+    records: removeRecordSyncFlags(recordsForPayload)
+  });
+};
+
+export const buildRecordTimeLabelSyncPayloadWithOperations = buildSyncPayloadWithOperations;
+
+export const flushPendingOperations = async ({
+  operations,
+  storageAdapter,
+  cloudAdapter,
+  storageKeys,
+  settingKeys = [],
+  groupOrderNormalizer,
+  clientId = 'recordtimelabel-client',
+  now = Date.now()
+} = {}) => {
+  const requestedOperations = toArray(operations);
+  if (requestedOperations.length === 0) {
+    return { success: true, syncedCount: 0, state: null, pendingOps: [] };
+  }
+  if (!storageAdapter?.load || !storageAdapter?.save) {
+    throw new Error('missing_storage_adapter');
+  }
+  if (!cloudAdapter?.load || !cloudAdapter?.save) {
+    throw new Error('missing_cloud_adapter');
+  }
+
+  const syncTime = resolveNow(now);
+  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));
+
+  if (pendingOpsForPayload.length === 0) {
+    return {
+      success: true,
+      syncedCount: 0,
+      state: buildLocalStateFromStorage(storageData, { settingKeys, groupOrderNormalizer }),
+      pendingOps: latestPendingOps
+    };
+  }
+
+  const remoteState = await cloudAdapter.load();
+  const localState = buildLocalStateFromStorage(storageData, { settingKeys, groupOrderNormalizer });
+  const payload = buildSyncPayloadWithOperations({
+    data: localState,
+    previousCloudData: remoteState || {},
+    pendingOps: pendingOpsForPayload,
+    syncMode: RECORD_TIMELABEL_SYNC_MODES.MERGE,
+    clientId,
+    now: syncTime,
+    groupOrderNormalizer
+  });
+
+  await cloudAdapter.save(payload);
+
+  const syncedIds = new Set(pendingOpsForPayload.map((operation) => operation?.id).filter(Boolean));
+  const remainingPendingOps = latestPendingOps.filter((operation) => !syncedIds.has(operation?.id));
+  let stateToPersist = normalizeState(payload || {});
+  remainingPendingOps.forEach((operation) => {
+    stateToPersist = applyRecordTimeLabelOperation(stateToPersist, operation);
+  });
+
+  await storageAdapter.save({
+    ...buildStoragePatchFromState(stateToPersist, { settingKeys, groupOrderNormalizer, now: syncTime }),
+    pendingOps: remainingPendingOps,
+    syncMeta: {
+      ...(storageData.syncMeta || {}),
+      lastSyncedAt: syncTime,
+      lastSyncedSchemaVersion: 1,
+      lastSyncedOperationCount: pendingOpsForPayload.length
+    }
+  });
+
+  return {
+    success: true,
+    syncedCount: pendingOpsForPayload.length,
+    state: stateToPersist,
+    pendingOps: remainingPendingOps
+  };
+};
+
+export const mergeRemoteStateIntoLocal = ({
+  localData = {},
+  remoteData = {},
+  pendingOps = localData.pendingOps || [],
+  settingKeys = [],
+  groupOrderNormalizer,
+  clientId = 'recordtimelabel-client',
+  now = Date.now()
+} = {}) => {
+  const localState = buildLocalStateFromStorage(localData, { settingKeys, groupOrderNormalizer });
+  const merged = mergeLocalRemote({
+    localState,
+    remoteState: remoteData || {},
+    pendingOps,
+    clientId,
+    now
+  });
+
+  let state = merged.state;
+  const hasPendingRecordReorder = toArray(pendingOps).some((operation) => (
+    operation?.type === OPERATION_TYPES.RECORD_REORDER
+  ));
+  const hasRecentRecordReorder = hasRecentLocalOperation(
+    localData,
+    remoteData,
+    OPERATION_TYPES.RECORD_REORDER
+  );
+  if (hasPendingRecordReorder || hasRecentRecordReorder) {
+    state = normalizeState({
+      ...state,
+      records: preserveRecordOrderFromLocal(state.records || {}, localState.records || {})
+    });
+  }
+
+  state = normalizeState({
+    ...state,
+    groupOrder: resolveMergedOrder({
+      localData,
+      remoteData,
+      pendingOps,
+      operationType: OPERATION_TYPES.GROUP_REORDER,
+      payloadKeys: ['groupOrder', 'order'],
+      stateKey: 'groupOrder',
+      normalizer: groupOrderNormalizer
+    }),
+    folderOrder: resolveMergedOrder({
+      localData,
+      remoteData,
+      pendingOps,
+      operationType: OPERATION_TYPES.FOLDER_REORDER,
+      payloadKeys: ['folderOrder', 'order'],
+      stateKey: 'folderOrder'
+    }),
+    expandedGroups: resolveMergedOrder({
+      localData,
+      remoteData,
+      pendingOps,
+      operationType: OPERATION_TYPES.EXPANDED_GROUPS_UPDATE,
+      payloadKeys: ['expandedGroups', 'groupIds', 'order', 'ids'],
+      stateKey: 'expandedGroups'
+    })
+  });
+
+  return {
+    ...merged,
+    state,
+    storagePatch: buildStoragePatchFromState(state, {
+      settingKeys,
+      groupOrderNormalizer,
+      now
+    })
+  };
+};
+
+export const createRecordTimeLabelController = ({
+  storageAdapter,
+  cloudAdapter,
+  storageKeys,
+  settingKeys = [],
+  groupOrderNormalizer,
+  clientId = 'recordtimelabel-client',
+  clock = () => Date.now(),
+  logger = console
+} = {}) => {
+  if (!storageAdapter?.load || !storageAdapter?.save) {
+    throw new Error('createRecordTimeLabelController requires a storageAdapter with load() and save()');
+  }
+
+  let state = normalizeState({});
+  let pendingOps = [];
+  let syncMeta = {};
+  let unsubscribeCloud = null;
+  const listeners = new Set();
+
+  const getSnapshot = () => ({
+    state: clone(state),
+    pendingOps: clone(pendingOps) || [],
+    syncMeta: { ...syncMeta }
+  });
+
+  const notify = (event) => {
+    const snapshot = controller.getSnapshot();
+    listeners.forEach((listener) => listener({ ...event, snapshot }));
+  };
+
+  const persist = async () => {
+    await storageAdapter.save({
+      ...buildStoragePatchFromState(state, {
+        settingKeys,
+        groupOrderNormalizer,
+        now: clock()
+      }),
+      pendingOps,
+      syncMeta
+    });
+  };
+
+  const controller = {
+    async init() {
+      const loaded = await storageAdapter.load(storageKeys);
+      state = buildLocalStateFromStorage(loaded || {}, { settingKeys, groupOrderNormalizer });
+      pendingOps = toArray(loaded?.pendingOps).map((operation) => ({ ...operation }));
+      syncMeta = loaded?.syncMeta && typeof loaded.syncMeta === 'object' ? { ...loaded.syncMeta } : {};
+
+      if (cloudAdapter?.load) {
+        const remoteState = await cloudAdapter.load();
+        const merged = mergeRemoteStateIntoLocal({
+          localData: { ...state, pendingOps, syncMeta },
+          remoteData: remoteState,
+          pendingOps,
+          settingKeys,
+          groupOrderNormalizer,
+          clientId,
+          now: clock()
+        });
+        state = merged.state;
+        await persist();
+      }
+
+      if (cloudAdapter?.subscribe) {
+        unsubscribeCloud = cloudAdapter.subscribe(async (remoteState) => {
+          await controller.handleRemoteUpdate(remoteState);
+        });
+      }
+
+      notify({ type: 'initialized' });
+      return getSnapshot();
+    },
+
+    getSnapshot,
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    async apply(operation) {
+      const nextOperation = {
+        ...operation,
+        id: operation.id || createOperation(operation.type, operation.payload, {
+          clientId,
+          now: clock()
+        }).id,
+        clientId: operation.clientId || clientId,
+        createdAt: operation.createdAt || clock()
+      };
+      state = applyRecordTimeLabelOperation(state, nextOperation);
+      pendingOps = [...pendingOps, nextOperation];
+      syncMeta = {
+        ...syncMeta,
+        lastLocalOperationAt: nextOperation.createdAt,
+        lastLocalOperationType: nextOperation.type
+      };
+      await persist();
+      notify({ type: 'local_applied', operation: nextOperation });
+      return getSnapshot();
+    },
+
+    async handleRemoteUpdate(remoteState) {
+      const merged = mergeRemoteStateIntoLocal({
+        localData: { ...state, pendingOps, syncMeta },
+        remoteData: remoteState,
+        pendingOps,
+        settingKeys,
+        groupOrderNormalizer,
+        clientId,
+        now: clock()
+      });
+      state = merged.state;
+      await persist();
+      notify({ type: 'remote_merged' });
+      return getSnapshot();
+    },
+
+    async sync(operations = pendingOps) {
+      if (!cloudAdapter?.save) {
+        return { success: false, reason: 'missing_cloud_save' };
+      }
+      try {
+        const result = await flushPendingOperations({
+          operations,
+          storageAdapter,
+          cloudAdapter,
+          storageKeys,
+          settingKeys,
+          groupOrderNormalizer,
+          clientId,
+          now: clock()
+        });
+        if (result.state) state = result.state;
+        pendingOps = result.pendingOps || [];
+        syncMeta = {
+          ...syncMeta,
+          lastSyncedAt: clock()
+        };
+        notify({ type: 'synced', result });
+        return result;
+      } catch (error) {
+        logger?.error?.('[RecordTimeLabelCore] controller sync failed', error);
+        syncMeta = {
+          ...syncMeta,
+          lastSyncError: error?.message || String(error)
+        };
+        await persist();
+        notify({ type: 'sync_error', error });
+        return { success: false, error };
+      }
+    },
+
+    async destroy() {
+      if (unsubscribeCloud) {
+        unsubscribeCloud();
+        unsubscribeCloud = null;
+      }
+      listeners.clear();
+    }
+  };
+
+  return controller;
+};
 
 export const createSyncEngine = ({
   storageAdapter,
@@ -931,16 +1833,35 @@ export const createSyncEngine = ({
 };
 
 export default {
-  RECORD_TIMELABEL_CORE_VERSION,
-  OPERATION_TYPES,
-  RECORD_TIMELABEL_SYNC_MODES,
-  normalizeState,
-  normalizeRecords,
-  mergeRecords,
-  mergeLocalRemote,
-  buildRecordTimeLabelSyncPayload,
-  buildDeletionTombstones,
-  applyOperation,
-  createOperation,
-  createSyncEngine
-};
+  RECORD_TIMELABEL_CORE_VERSION,
+  OPERATION_TYPES,
+  RECORD_TIMELABEL_SYNC_MODES,
+  RECORD_TIMELABEL_CLOUD_SCHEMAS,
+  FIRESTORE_V2_SETTINGS_DOC_ID,
+  normalizeState,
+  hasMeaningfulRecordTimeLabelCloudState,
+  buildRecordTimeLabelContentFingerprint,
+  buildMigratedRecordTimeLabelV2State,
+  normalizeRecords,
+  mergeRecords,
+  mergeLocalRemote,
+  preserveRecordOrderFromLocal,
+  buildRecordTimeLabelSyncPayload,
+  buildSyncPayloadWithOperations,
+  buildRecordTimeLabelSyncPayloadWithOperations,
+  buildDeletionTombstones,
+  buildSettingsFromStorage,
+  buildLocalStateFromStorage,
+  buildStoragePatchFromState,
+  buildFirestoreV1UserPatch,
+  buildFirestoreV2LogicalPaths,
+  buildFirestoreV2DocumentsFromState,
+  buildStateFromFirestoreV2Documents,
+  flushPendingOperations,
+  mergeRemoteStateIntoLocal,
+  applyOperation,
+  applyRecordTimeLabelOperation,
+  createOperation,
+  createSyncEngine,
+  createRecordTimeLabelController
+};