@recordtimelabel/core 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @recordtimelabel/core
+
+Shared RecordTimeLabel data model, normalization, merge logic, operation reducer, and sync engine.
+
+## Scope
+
+This package is intentionally platform-neutral. It must not import React, Firebase, Chrome extension APIs, Electron APIs, or app-specific UI code.
+
+Current consumers:
+
+- `D:\Programming\RecordTimeLabel`
+- `D:\Programming\YouTwitchDownloader`
+
+During local development both apps consume it 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.
+
+## Public API
+
+- `normalizeState(input)`
+- `normalizeRecords(records, options)`
+- `mergeLocalRemote({ localState, remoteState, pendingOps, clientId, now })`
+- `applyOperation(state, operation)`
+- `createSyncEngine({ storageAdapter, cloudAdapter, clientId, clock, logger })`
+- `createOperation(type, payload, options)`
+- `OPERATION_TYPES`
+
+## Firestore v1 Compatibility
+
+Phase 1 keeps the existing `users/{uid}` document shape:
+
+- `folders`
+- `records`
+- `groupOrder`
+- `folderOrder`
+- `expandedGroups`
+- `settings`
+
+The core also normalizes and preserves these compatibility metadata fields:
+
+- `rtlSyncMeta`
+- `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.
+
+## Test
+
+```bash
+npm test
+```

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@recordtimelabel/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}

package/src/index.js

@@ -0,0 +1,809 @@
+const DEFAULT_FOLDER_ID = 'uncategorized';
+const VIRTUAL_FOLDER_IDS = new Set(['all']);
+const REQUIRED_FOLDERS = [
+  { id: 'all', name: 'All' },
+  { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
+];
+
+export const RECORD_TIMELABEL_CORE_VERSION = '0.1.0';
+
+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'
+});
+
+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') {
+    return Number.isFinite(value) ? value : 0;
+  }
+  const parsed = new Date(value || 0).getTime();
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+const getRecordTime = (record = {}) => Math.max(
+  toFiniteTimestamp(record.updatedAt),
+  toFiniteTimestamp(record.createdAt),
+  toFiniteTimestamp(record.syncedAt)
+);
+
+const hasValue = (value) => {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string') return value.trim() !== '';
+  return true;
+};
+
+const richFields = [
+  'note',
+  'title',
+  'streamerName',
+  'channelName',
+  'channelHandle',
+  'channelUrl',
+  'url',
+  'videoUrl',
+  'downloadUrl',
+  'liveTime',
+  'originalLiveTime',
+  'platform',
+  'hasVod',
+  'vodId',
+  'vodTitle',
+  'avatarUrl',
+  'm3u8Type'
+];
+
+const getRecordRichness = (record = {}) => richFields.reduce(
+  (score, field) => score + (hasValue(record[field]) ? 1 : 0),
+  0
+);
+
+const getRecordPriority = (record = {}) => {
+  let score = 0;
+  if (record.pendingSync === true) score += 64;
+  if (record.hasVod === true) score += 16;
+  if (record.videoUrl) score += 8;
+  if (record.downloadUrl) score += 4;
+  if (record.note) score += 2;
+  return score + getRecordRichness(record);
+};
+
+const normalizeId = (value) => {
+  if (typeof value !== 'string' && typeof value !== 'number') return '';
+  return String(value).trim();
+};
+
+const safeFolderId = (folderId) => {
+  const normalized = normalizeId(folderId);
+  if (!normalized || VIRTUAL_FOLDER_IDS.has(normalized)) return DEFAULT_FOLDER_ID;
+  return normalized;
+};
+
+const normalizeOrder = (value) => Array.from(new Set(
+  toArray(value).map(normalizeId).filter(Boolean)
+));
+
+const normalizeTombstones = (value) => {
+  if (!value) return {};
+  const entries = Array.isArray(value)
+    ? value.map((entry) => [entry?.id || entry?.recordId || entry?.folderId, entry])
+    : Object.entries(value);
+
+  return entries.reduce((result, [rawId, rawTombstone]) => {
+    const id = normalizeId(rawId);
+    if (!id) return result;
+    const tombstone = rawTombstone && typeof rawTombstone === 'object'
+      ? { ...rawTombstone }
+      : {};
+    const deletedAt = toFiniteTimestamp(tombstone.deletedAt || tombstone.updatedAt || tombstone.createdAt);
+    result[id] = {
+      ...tombstone,
+      id,
+      deletedAt: deletedAt || Date.now()
+    };
+    return result;
+  }, {});
+};
+
+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)) {
+      merged[id] = { ...tombstone };
+    }
+  });
+  return merged;
+};
+
+const resolveRecordFolderId = (folderId, record = {}) => {
+  const candidates = [
+    record.folderId,
+    record.originalFolderId,
+    record.sourceFolderId,
+    record.targetFolderId,
+    folderId
+  ];
+  const match = candidates.map(normalizeId).find((id) => id && !VIRTUAL_FOLDER_IDS.has(id));
+  return match || DEFAULT_FOLDER_ID;
+};
+
+const pickPreferredRecord = (left, right) => {
+  if (!left) return right ? { ...right } : null;
+  if (!right) return { ...left };
+
+  const leftTime = getRecordTime(left);
+  const rightTime = getRecordTime(right);
+  if (leftTime !== rightTime) {
+    return rightTime > leftTime ? right : left;
+  }
+
+  const leftPriority = getRecordPriority(left);
+  const rightPriority = getRecordPriority(right);
+  if (leftPriority !== rightPriority) {
+    return rightPriority > leftPriority ? right : left;
+  }
+
+  return left;
+};
+
+export const mergeRecords = (left, right) => {
+  if (!left) return right ? { ...right } : null;
+  if (!right) return { ...left };
+
+  const preferred = pickPreferredRecord(left, right);
+  const secondary = preferred === left ? right : left;
+  const merged = { ...secondary, ...preferred };
+
+  richFields.forEach((field) => {
+    if (!hasValue(merged[field])) {
+      if (hasValue(preferred?.[field])) {
+        merged[field] = preferred[field];
+      } else if (hasValue(secondary?.[field])) {
+        merged[field] = secondary[field];
+      }
+    }
+  });
+
+  if (left.hasVod || right.hasVod) merged.hasVod = true;
+  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();
+
+  Object.entries(source).forEach(([folderId, folderRecords]) => {
+    const safeList = toArray(folderRecords);
+    safeList.forEach((record, index) => {
+      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,
+        id
+      };
+      delete normalizedRecord.folderId;
+      delete normalizedRecord.sortIndex;
+
+      const tombstone = tombstones[id];
+      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= getRecordTime(normalizedRecord)) {
+        return;
+      }
+
+      const existing = placements.get(id);
+      if (!existing) {
+        normalized[targetFolderId].push(normalizedRecord);
+        placements.set(id, {
+          folderId: targetFolderId,
+          index: normalized[targetFolderId].length - 1,
+          record: normalizedRecord
+        });
+        return;
+      }
+
+      const merged = mergeRecords(existing.record, normalizedRecord);
+      const preferred = pickPreferredRecord(existing.record, normalizedRecord);
+      const shouldMove = preferred === normalizedRecord && targetFolderId !== existing.folderId;
+      const samePriorityNewer = getRecordTime(normalizedRecord) > getRecordTime(existing.record);
+
+      if (shouldMove || samePriorityNewer) {
+        normalized[existing.folderId][existing.index] = null;
+        normalized[targetFolderId].push(merged);
+        placements.set(id, {
+          folderId: targetFolderId,
+          index: normalized[targetFolderId].length - 1,
+          record: merged
+        });
+      } else {
+        normalized[existing.folderId][existing.index] = merged;
+        placements.set(id, {
+          ...existing,
+          record: merged
+        });
+      }
+    });
+  });
+
+  Object.keys(normalized).forEach((folderId) => {
+    normalized[folderId] = toArray(normalized[folderId]).filter(Boolean);
+  });
+
+  return normalized;
+};
+
+const ensureFolders = (folders = []) => {
+  const seen = new Set();
+  const nextFolders = [];
+  toArray(folders).forEach((folder) => {
+    if (!folder || typeof folder !== 'object') return;
+    const id = normalizeId(folder.id);
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    nextFolders.push({ ...folder, id });
+  });
+
+  REQUIRED_FOLDERS.forEach((folder) => {
+    if (!seen.has(folder.id)) {
+      seen.add(folder.id);
+      nextFolders.unshift({ ...folder });
+    }
+  });
+
+  return nextFolders.sort((left, right) => {
+    const leftRequired = REQUIRED_FOLDERS.findIndex((folder) => folder.id === left.id);
+    const rightRequired = REQUIRED_FOLDERS.findIndex((folder) => folder.id === right.id);
+    if (leftRequired !== -1 || rightRequired !== -1) {
+      if (leftRequired === -1) return 1;
+      if (rightRequired === -1) return -1;
+      return leftRequired - rightRequired;
+    }
+    return 0;
+  });
+};
+
+const ensureRecordFolders = (records, folders) => {
+  const nextRecords = { ...records };
+  folders.forEach((folder) => {
+    if (!nextRecords[folder.id]) nextRecords[folder.id] = [];
+  });
+  if (!nextRecords.all) nextRecords.all = [];
+  if (!nextRecords[DEFAULT_FOLDER_ID]) nextRecords[DEFAULT_FOLDER_ID] = [];
+  nextRecords.all = [];
+  return nextRecords;
+};
+
+const getFolderTime = (folder = {}) => Math.max(
+  toFiniteTimestamp(folder.updatedAt),
+  toFiniteTimestamp(folder.createdAt),
+  toFiniteTimestamp(folder.lastModified)
+);
+
+const mergeFolders = (remoteFolders = [], localFolders = [], deletedFolderTombstones = {}) => {
+  const byId = new Map();
+
+  const visit = (folder, source) => {
+    if (!folder || typeof folder !== 'object') return;
+    const id = normalizeId(folder.id);
+    if (!id) return;
+
+    const tombstone = deletedFolderTombstones[id];
+    if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= getFolderTime(folder)) {
+      return;
+    }
+
+    const current = byId.get(id);
+    if (!current) {
+      byId.set(id, { ...folder, id });
+      return;
+    }
+
+    const currentTime = getFolderTime(current);
+    const nextTime = getFolderTime(folder);
+    if (nextTime > currentTime || (nextTime === currentTime && source === 'local')) {
+      byId.set(id, { ...current, ...folder, id });
+    }
+  };
+
+  toArray(remoteFolders).forEach((folder) => visit(folder, 'remote'));
+  toArray(localFolders).forEach((folder) => visit(folder, 'local'));
+
+  return Array.from(byId.values());
+};
+
+const mergeOrderWithLocalIds = (remoteOrder = [], localOrder = [], allowedIds = new Set()) => {
+  const merged = normalizeOrder(remoteOrder).filter((id) => allowedIds.has(id));
+  normalizeOrder(localOrder).forEach((id) => {
+    if (allowedIds.has(id) && !merged.includes(id)) {
+      merged.push(id);
+    }
+  });
+  return merged;
+};
+
+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
+  );
+
+  return {
+    folders,
+    records,
+    groupOrder: normalizeOrder(input.groupOrder),
+    folderOrder: normalizeOrder(input.folderOrder),
+    expandedGroups: normalizeOrder(input.expandedGroups),
+    settings: input.settings && typeof input.settings === 'object' ? { ...input.settings } : {},
+    rtlSyncMeta: {
+      schemaVersion: 1,
+      ...(input.rtlSyncMeta && typeof input.rtlSyncMeta === 'object' ? input.rtlSyncMeta : {})
+    },
+    deletedRecordTombstones,
+    deletedFolderTombstones,
+    lastModified: toFiniteTimestamp(input.lastModified || input.updatedAt || input.lastUpdated)
+  };
+};
+
+const removeRecordById = (records, recordId) => {
+  const nextRecords = {};
+  Object.entries(records || {}).forEach(([folderId, folderRecords]) => {
+    nextRecords[folderId] = toArray(folderRecords).filter((record) => record?.id !== recordId);
+  });
+  return nextRecords;
+};
+
+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;
+};
+
+export const createOperation = (type, payload = {}, options = {}) => ({
+  id: options.id || `${type}:${options.clientId || 'client'}:${options.now || Date.now()}:${Math.random().toString(36).slice(2, 10)}`,
+  type,
+  payload,
+  clientId: options.clientId || null,
+  createdAt: options.now || Date.now()
+});
+
+export const applyOperation = (state = {}, operation = {}) => {
+  const normalized = normalizeState(state);
+  const type = operation.type;
+  const payload = operation.payload || {};
+  const operationTime = toFiniteTimestamp(operation.createdAt || payload.updatedAt || Date.now()) || Date.now();
+
+  const nextState = clone(normalized);
+
+  switch (type) {
+    case OPERATION_TYPES.RECORD_CREATE: {
+      const record = payload.record && typeof payload.record === 'object' ? { ...payload.record } : null;
+      if (!record) return normalized;
+      const recordId = normalizeId(record.id || payload.recordId);
+      if (!recordId) return normalized;
+      const tombstone = nextState.deletedRecordTombstones[recordId];
+      const recordTime = getRecordTime(record) || operationTime;
+      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= recordTime) {
+        return normalized;
+      }
+
+      const folderId = safeFolderId(payload.folderId || record.folderId);
+      const cleanedRecord = {
+        ...record,
+        id: recordId,
+        updatedAt: record.updatedAt || operationTime
+      };
+      delete cleanedRecord.folderId;
+
+      nextState.records = removeRecordById(nextState.records, recordId);
+      nextState.records[folderId] = [
+        cleanedRecord,
+        ...toArray(nextState.records[folderId])
+      ];
+      break;
+    }
+
+    case OPERATION_TYPES.RECORD_UPDATE: {
+      const recordId = normalizeId(payload.recordId || payload.id || payload.record?.id);
+      if (!recordId) return normalized;
+      const entry = findRecordEntry(nextState.records, recordId);
+      if (!entry) return normalized;
+      const patch = payload.patch || payload.record || {};
+      const updatedRecord = mergeRecords(entry.record, {
+        ...entry.record,
+        ...patch,
+        id: recordId,
+        updatedAt: patch.updatedAt || operationTime
+      });
+      nextState.records[entry.folderId][entry.index] = updatedRecord;
+      break;
+    }
+
+    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;
+      const movedRecord = {
+        ...entry.record,
+        ...(payload.record || {}),
+        id: recordId,
+        updatedAt: payload.updatedAt || operationTime
+      };
+      nextState.records = removeRecordById(nextState.records, recordId);
+      nextState.records[targetFolderId] = [
+        ...toArray(nextState.records[targetFolderId]),
+        movedRecord
+      ];
+      break;
+    }
+
+    case OPERATION_TYPES.RECORD_DELETE: {
+      const recordId = normalizeId(payload.recordId || payload.id);
+      if (!recordId) return normalized;
+      nextState.records = removeRecordById(nextState.records, recordId);
+      nextState.deletedRecordTombstones[recordId] = {
+        id: recordId,
+        deletedAt: payload.deletedAt || operationTime,
+        clientId: operation.clientId || payload.clientId || null,
+        operationId: operation.id || null
+      };
+      break;
+    }
+
+    case OPERATION_TYPES.FOLDER_CREATE: {
+      const folder = payload.folder && typeof payload.folder === 'object' ? { ...payload.folder } : null;
+      const folderId = normalizeId(folder?.id || payload.folderId);
+      if (!folderId) return normalized;
+      const existingIndex = nextState.folders.findIndex((item) => item.id === folderId);
+      const nextFolder = {
+        ...(folder || {}),
+        id: folderId,
+        updatedAt: folder?.updatedAt || operationTime
+      };
+      if (existingIndex === -1) {
+        nextState.folders.push(nextFolder);
+      } else {
+        nextState.folders[existingIndex] = { ...nextState.folders[existingIndex], ...nextFolder };
+      }
+      if (!nextState.records[folderId]) nextState.records[folderId] = [];
+      break;
+    }
+
+    case OPERATION_TYPES.FOLDER_UPDATE: {
+      const folderId = normalizeId(payload.folderId || payload.id || payload.folder?.id);
+      if (!folderId) return normalized;
+      const patch = payload.patch || payload.folder || {};
+      nextState.folders = nextState.folders.map((folder) => (
+        folder.id === folderId
+          ? { ...folder, ...patch, id: folderId, updatedAt: patch.updatedAt || operationTime }
+          : folder
+      ));
+      break;
+    }
+
+    case OPERATION_TYPES.FOLDER_DELETE: {
+      const folderId = normalizeId(payload.folderId || payload.id);
+      if (!folderId || folderId === 'all' || folderId === DEFAULT_FOLDER_ID) return normalized;
+      nextState.folders = nextState.folders.filter((folder) => folder.id !== folderId);
+      delete nextState.records[folderId];
+      nextState.folderOrder = nextState.folderOrder.filter((id) => id !== folderId);
+      nextState.groupOrder = nextState.groupOrder.filter((id) => id !== folderId);
+      nextState.deletedFolderTombstones[folderId] = {
+        id: folderId,
+        deletedAt: payload.deletedAt || operationTime,
+        clientId: operation.clientId || payload.clientId || null,
+        operationId: operation.id || null
+      };
+      break;
+    }
+
+    case OPERATION_TYPES.FOLDER_REORDER:
+      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 || {})
+      };
+      break;
+
+    default:
+      return normalized;
+  }
+
+  nextState.lastModified = Math.max(nextState.lastModified || 0, operationTime);
+  nextState.rtlSyncMeta = {
+    ...nextState.rtlSyncMeta,
+    lastOperationId: operation.id || nextState.rtlSyncMeta.lastOperationId || null,
+    lastClientId: operation.clientId || nextState.rtlSyncMeta.lastClientId || null,
+    lastOperationAt: operationTime
+  };
+
+  return normalizeState(nextState);
+};
+
+export const mergeLocalRemote = ({
+  localState = {},
+  remoteState = {},
+  pendingOps = [],
+  clientId = null,
+  now = Date.now()
+} = {}) => {
+  const local = normalizeState(localState);
+  const remote = normalizeState(remoteState);
+  const deletedRecordTombstones = mergeTombstones(
+    remote.deletedRecordTombstones,
+    local.deletedRecordTombstones
+  );
+  const deletedFolderTombstones = mergeTombstones(
+    remote.deletedFolderTombstones,
+    local.deletedFolderTombstones
+  );
+  const folders = mergeFolders(remote.folders, local.folders, deletedFolderTombstones);
+  const folderIds = new Set(ensureFolders(folders).map((folder) => folder.id));
+
+  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 },
+    deletedRecordTombstones,
+    deletedFolderTombstones,
+    rtlSyncMeta: {
+      ...remote.rtlSyncMeta,
+      ...local.rtlSyncMeta,
+      lastMergedAt: now,
+      lastMergedClientId: clientId
+    },
+    lastModified: Math.max(remote.lastModified || 0, local.lastModified || 0)
+  });
+
+  Object.entries(local.records || {}).forEach(([folderId, folderRecords]) => {
+    toArray(folderRecords).forEach((localRecord) => {
+      if (!localRecord?.id) return;
+      const tombstone = deletedRecordTombstones[localRecord.id];
+      const recordTime = getRecordTime(localRecord);
+      if (tombstone && toFiniteTimestamp(tombstone.deletedAt) >= recordTime) return;
+
+      const remoteEntry = findRecordEntry(mergedState.records, localRecord.id);
+      const shouldKeepLocal = localRecord.pendingSync === true ||
+        recordTime > getRecordTime(remoteEntry?.record || {});
+      if (!shouldKeepLocal) return;
+
+      const targetFolderId = safeFolderId(folderId);
+      const mergedRecord = remoteEntry
+        ? mergeRecords(remoteEntry.record, localRecord)
+        : { ...localRecord };
+      mergedState.records = removeRecordById(mergedState.records, localRecord.id);
+      mergedState.records[targetFolderId] = [
+        mergedRecord,
+        ...toArray(mergedState.records[targetFolderId])
+      ];
+    });
+  });
+
+  toArray(pendingOps).forEach((operation) => {
+    mergedState = applyOperation(mergedState, operation);
+  });
+
+  return {
+    state: normalizeState(mergedState),
+    pendingOps: toArray(pendingOps).map((operation) => ({ ...operation })),
+    hasPendingOps: toArray(pendingOps).length > 0,
+    mergedAt: now
+  };
+};
+
+export const createSyncEngine = ({
+  storageAdapter,
+  cloudAdapter,
+  clientId = 'recordtimelabel-client',
+  clock = () => Date.now(),
+  logger = console
+} = {}) => {
+  if (!storageAdapter?.load || !storageAdapter?.save) {
+    throw new Error('createSyncEngine requires a storageAdapter with load() and save()');
+  }
+
+  let state = normalizeState({});
+  let pendingOps = [];
+  let syncMeta = {};
+  let unsubscribeCloud = null;
+  const listeners = new Set();
+
+  const notify = (event) => {
+    const snapshot = engine.getSnapshot();
+    listeners.forEach((listener) => listener({ ...event, snapshot }));
+  };
+
+  const persist = async () => {
+    await storageAdapter.save({
+      state,
+      pendingOps,
+      syncMeta
+    });
+  };
+
+  const engine = {
+    async init() {
+      const loaded = await storageAdapter.load();
+      state = normalizeState(loaded?.state || loaded || {});
+      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 = mergeLocalRemote({
+          localState: state,
+          remoteState,
+          pendingOps,
+          clientId,
+          now: clock()
+        });
+        state = merged.state;
+        await persist();
+      }
+
+      if (cloudAdapter?.subscribe) {
+        unsubscribeCloud = cloudAdapter.subscribe(async (remoteState) => {
+          await engine.handleRemoteUpdate(remoteState);
+        });
+      }
+
+      notify({ type: 'initialized' });
+      return engine.getSnapshot();
+    },
+
+    getSnapshot() {
+      return {
+        state: clone(state),
+        pendingOps: clone(pendingOps) || [],
+        syncMeta: { ...syncMeta }
+      };
+    },
+
+    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 = applyOperation(state, nextOperation);
+      pendingOps = [...pendingOps, nextOperation];
+      syncMeta = {
+        ...syncMeta,
+        lastLocalOperationAt: nextOperation.createdAt
+      };
+      await persist();
+      notify({ type: 'local_applied', operation: nextOperation });
+      return engine.getSnapshot();
+    },
+
+    async handleRemoteUpdate(remoteState) {
+      const merged = mergeLocalRemote({
+        localState: state,
+        remoteState,
+        pendingOps,
+        clientId,
+        now: clock()
+      });
+      state = merged.state;
+      await persist();
+      notify({ type: 'remote_merged' });
+      return engine.getSnapshot();
+    },
+
+    async sync() {
+      if (!cloudAdapter?.save) {
+        return { success: false, reason: 'missing_cloud_save' };
+      }
+      try {
+        await cloudAdapter.save(state, {
+          pendingOps: clone(pendingOps) || [],
+          clientId,
+          syncMeta
+        });
+        pendingOps = [];
+        syncMeta = {
+          ...syncMeta,
+          lastSyncedAt: clock()
+        };
+        state = normalizeState({
+          ...state,
+          records: Object.fromEntries(Object.entries(state.records).map(([folderId, records]) => [
+            folderId,
+            toArray(records).map((record) => {
+              const cleanRecord = { ...record };
+              delete cleanRecord.pendingSync;
+              delete cleanRecord.syncAttempts;
+              return cleanRecord;
+            })
+          ]))
+        });
+        await persist();
+        notify({ type: 'synced' });
+        return { success: true };
+      } catch (error) {
+        logger?.error?.('[RecordTimeLabelCore] 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 engine;
+};
+
+export default {
+  RECORD_TIMELABEL_CORE_VERSION,
+  OPERATION_TYPES,
+  normalizeState,
+  normalizeRecords,
+  mergeRecords,
+  mergeLocalRemote,
+  applyOperation,
+  createOperation,
+  createSyncEngine
+};