@recordtimelabel/core 0.3.3 → 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.3';
+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;
@@ -562,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']);
@@ -582,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 = {}) => {
@@ -594,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
@@ -1115,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 = {
@@ -1669,7 +1728,6 @@ export const buildFirestoreV2DocumentsFromState = (state = {}, options = {}) =>
     settings: normalized.settings || {},
     groupOrder: normalizeGroupOrderForOption(normalized.groupOrder, options.groupOrderNormalizer),
     folderOrder: normalized.folderOrder,
-    expandedGroups: normalized.expandedGroups,
     rtlSyncMeta: {
       ...(normalized.rtlSyncMeta || {}),
       schemaVersion: 2,
@@ -1760,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,
@@ -1911,7 +1976,6 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
     settings: rootDoc.settings || {},
     groupOrder: normalizeGroupOrderForOption(rootDoc.groupOrder, options.groupOrderNormalizer),
     folderOrder: rootDoc.folderOrder || [],
-    expandedGroups: rootDoc.expandedGroups || [],
     rtlSyncMeta: rootDoc.rtlSyncMeta || {},
     deletedRecordTombstones: mergeLifecycleTombstoneSources(
       rootDoc.deletedRecordTombstones,
@@ -2538,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,
@@ -3075,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;
@@ -3083,6 +4182,16 @@ 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);
@@ -3284,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;
@@ -3300,10 +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'])
-          );
         }
         rtlSetRoot(nextDocuments.root, appliedRoot);
         changed = true;
@@ -3336,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
@@ -3469,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}});
   }
@@ -3515,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,
@@ -3524,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,
@@ -3551,12 +4656,15 @@ export default {
   extendFirestoreV2OperationReadPlanWithTrash,
   planFirestoreV2OperationChanges,
   estimateFirestoreV2WriteUnits,
+  normalizeRecordTimeLabelOperationResults,
+  normalizeRecordTimeLabelEnvelopeResponse,
   buildOperationsFromSnapshotDiff,
   flushPendingOperations,
   mergeRemoteStateIntoLocal,
   applyOperation,
   applyRecordTimeLabelOperation,
   createOperation,
+  createRecordTimeLabelSyncEngine,
   createSyncEngine,
   createRecordTimeLabelController
 };