@recordtimelabel/core 0.4.7 → 0.6.0

package/src/domain/twitch-vod.js

@@ -0,0 +1,303 @@
+import {fingerprintCanonicalJson} from './hash.js';
+import {buildRecordTimeLabelGroupIndex} from './group-identity.js';
+import {
+  DEFAULT_UNKNOWN_TITLE,
+  collectNonVirtualRecords,
+  extractTwitchVodIdFromUrl,
+  getFirstMatchingUrlValue,
+  getRecordUrls,
+  normalizeId,
+  normalizeRecordPlatform,
+  normalizeText,
+  parseElapsedSeconds
+} from './shared.js';
+import {parseUtcMillis} from './time.js';
+
+const TITLE_BRACKET_PATTERN = /\[[^\]]*\]|\([^)]*\)|\{[^}]*\}/g;
+const NON_WORD_PATTERN = /[^\p{L}\p{N}\s]/gu;
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * MINUTE_MS;
+const RECORD_AFTER_START_GRACE_MS = 10 * MINUTE_MS;
+const STREAM_START_GRACE_MS = 45 * MINUTE_MS;
+const ELAPSED_START_TOLERANCE_MS = 45 * MINUTE_MS;
+const MAX_REASONABLE_STREAM_MS = 48 * HOUR_MS;
+
+const getVodStartMs = (vod = {}) => parseUtcMillis(vod.publishedAt || vod.createdAt);
+
+const getNextVodStartMs = (value) => (
+  typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : parseUtcMillis(value)
+);
+
+export const normalizeVodTitleForMatch = (value) => String(value || '')
+  .toLowerCase()
+  .normalize('NFKC')
+  .replace(TITLE_BRACKET_PATTERN, ' ')
+  .replace(NON_WORD_PATTERN, ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
+
+export const calculateVodTitleSimilarity = (expectedTitle, candidateTitle) => {
+  const expected = normalizeVodTitleForMatch(expectedTitle);
+  const candidate = normalizeVodTitleForMatch(candidateTitle);
+  if (!expected || !candidate) return 0;
+  if (expected === candidate) return 1;
+  if (expected.includes(candidate) || candidate.includes(expected)) return 0.9;
+
+  const expectedTokens = new Set(expected.split(' ').filter(Boolean));
+  const candidateTokens = new Set(candidate.split(' ').filter(Boolean));
+  if (expectedTokens.size === 0 || candidateTokens.size === 0) return 0;
+
+  let intersection = 0;
+  expectedTokens.forEach((token) => {
+    if (candidateTokens.has(token)) intersection += 1;
+  });
+  const union = new Set([...expectedTokens, ...candidateTokens]).size;
+  return union > 0 ? intersection / union : 0;
+};
+
+export const scoreTwitchVodCandidate = (vod = {}, context = {}) => {
+  const recordMs = parseUtcMillis(context.recordTimestamp);
+  const streamStartMs = parseUtcMillis(context.streamCreatedAt || context.streamStartedAt);
+  const elapsedSeconds = parseElapsedSeconds(context.recordLiveTimeSeconds);
+  const targetSeconds = parseElapsedSeconds(context.recordTargetTimeSeconds) ?? elapsedSeconds;
+  const vodStartMs = getVodStartMs(vod);
+  const nextVodStartMs = getNextVodStartMs(context.nextVodStartMs || context.nextVodStartAt);
+
+  if (!vod?.id || vodStartMs === null) return null;
+
+  const expectedStartMs = recordMs !== null && elapsedSeconds !== null
+    ? recordMs - (elapsedSeconds * 1000)
+    : null;
+  const lengthSeconds = parseElapsedSeconds(vod.lengthSeconds);
+  const hasStableAnchor = Boolean(streamStartMs !== null || expectedStartMs !== null);
+  const matchedBy = [];
+  let score = 0;
+  const streamAnchorMs = expectedStartMs !== null ? expectedStartMs : streamStartMs;
+  const targetAbsoluteMs = targetSeconds !== null && streamAnchorMs !== null
+    ? streamAnchorMs + (targetSeconds * 1000)
+    : recordMs;
+  const lengthEndMs = lengthSeconds !== null ? vodStartMs + (lengthSeconds * 1000) : null;
+  const inferredEndMs = nextVodStartMs !== null &&
+    nextVodStartMs > vodStartMs &&
+    nextVodStartMs - vodStartMs <= MAX_REASONABLE_STREAM_MS
+    ? nextVodStartMs
+    : null;
+  const vodEndMs = lengthEndMs || inferredEndMs;
+
+  if (targetAbsoluteMs !== null) {
+    if (targetAbsoluteMs < vodStartMs - RECORD_AFTER_START_GRACE_MS) return null;
+    if (vodEndMs !== null && targetAbsoluteMs >= vodEndMs + RECORD_AFTER_START_GRACE_MS) return null;
+    if (vodEndMs !== null) {
+      score += 80;
+      matchedBy.push('target-window');
+    }
+  }
+
+  if (expectedStartMs !== null) {
+    const startDelta = Math.abs(vodStartMs - expectedStartMs);
+    if (startDelta <= ELAPSED_START_TOLERANCE_MS) {
+      const closeness = 1 - (startDelta / ELAPSED_START_TOLERANCE_MS);
+      score += 85 + (closeness * 15);
+      matchedBy.push('elapsed-start');
+    }
+  }
+
+  if (streamStartMs !== null && recordMs !== null) {
+    const startsInsideStreamWindow =
+      vodStartMs >= streamStartMs - STREAM_START_GRACE_MS &&
+      vodStartMs <= recordMs + RECORD_AFTER_START_GRACE_MS;
+    if (startsInsideStreamWindow) {
+      const streamSpan = Math.max(recordMs - streamStartMs, 1);
+      const positionPenalty = Math.min(Math.max(vodStartMs - streamStartMs, 0) / streamSpan, 1) * 15;
+      score += 70 - positionPenalty;
+      matchedBy.push('stream-window');
+    }
+  }
+
+  if (recordMs !== null && vodEndMs !== null) {
+    const containsRecord =
+      recordMs >= vodStartMs - RECORD_AFTER_START_GRACE_MS &&
+      recordMs <= vodEndMs + RECORD_AFTER_START_GRACE_MS;
+    if (containsRecord) {
+      score += 60;
+      matchedBy.push('duration-window');
+    }
+  }
+
+  if (!hasStableAnchor && recordMs !== null) {
+    const recordOffsetMs = recordMs - vodStartMs;
+    if (recordOffsetMs >= -RECORD_AFTER_START_GRACE_MS && recordOffsetMs <= MAX_REASONABLE_STREAM_MS) {
+      const closeness = 1 - Math.min(Math.max(recordOffsetMs, 0) / MAX_REASONABLE_STREAM_MS, 1);
+      score += 30 + (closeness * 20);
+      matchedBy.push('legacy-time-window');
+    }
+  }
+
+  if (matchedBy.length === 0) return null;
+
+  const titleSimilarity = calculateVodTitleSimilarity(context.expectedTitle, vod.title || '');
+  score += titleSimilarity * 10;
+  if (score < (hasStableAnchor ? 55 : 25)) return null;
+
+  const vodTimeOffsetSeconds = targetSeconds !== null && matchedBy.includes('elapsed-start')
+    ? targetSeconds
+    : targetSeconds !== null && streamAnchorMs !== null
+      ? Math.max(0, Math.floor(targetSeconds - ((vodStartMs - streamAnchorMs) / 1000)))
+      : (recordMs !== null
+        ? Math.max(0, Math.floor((recordMs - vodStartMs) / 1000))
+        : targetSeconds);
+
+  return {
+    vod,
+    score,
+    matchedBy,
+    titleSimilarity,
+    vodStartAt: new Date(vodStartMs).toISOString(),
+    vodTimeOffsetSeconds
+  };
+};
+
+export const selectBestMatchingTwitchVod = (items = [], context = {}) => {
+  const normalizedItems = (Array.isArray(items) ? items : [])
+    .map((item) => item?.node || item)
+    .map((vod) => ({vod, startMs: getVodStartMs(vod)}))
+    .filter((entry) => entry.vod?.id && entry.startMs !== null)
+    .sort((a, b) => a.startMs - b.startMs);
+
+  return normalizedItems
+    .map((entry, index) => scoreTwitchVodCandidate(entry.vod, {
+      ...context,
+      nextVodStartMs: normalizedItems[index + 1]?.startMs ?? null
+    }))
+    .filter(Boolean)
+    .sort((a, b) => b.score - a.score)[0] || null;
+};
+
+const valuesEqual = (left, right) => {
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((value, index) => valuesEqual(value, right[index]));
+  }
+  return left === right;
+};
+
+const recordHasConflictingIdentity = (record, source) => {
+  const recordStreamId = normalizeText(record?.streamId);
+  const sourceStreamId = normalizeText(source?.streamId);
+  if (recordStreamId && sourceStreamId && recordStreamId !== sourceStreamId) return true;
+  const recordVodId = normalizeText(record?.vodId) || getFirstMatchingUrlValue(record, extractTwitchVodIdFromUrl);
+  const sourceVodId = normalizeText(source?.vodId) || getFirstMatchingUrlValue(source, extractTwitchVodIdFromUrl);
+  if (recordVodId && sourceVodId && recordVodId !== sourceVodId) return true;
+  return false;
+};
+
+export const buildRecordTimeLabelVodPatchOperationId = (recordId, patch = {}) => (
+  `record.update:${normalizeId(recordId)}:vod-patch:${fingerprintCanonicalJson(patch || {})}`
+);
+
+export const buildKnownTwitchVodRecordPatches = ({
+  records = [],
+  groupIndex = null,
+  fallbackPlatform,
+  unknownTitle = DEFAULT_UNKNOWN_TITLE
+} = {}) => {
+  const safeRecords = collectNonVirtualRecords(records);
+  const index = groupIndex || buildRecordTimeLabelGroupIndex({
+    records: safeRecords,
+    fallbackPlatform,
+    unknownTitle
+  });
+  const conflictGroupIds = new Set(index.diagnostics?.conflictGroupIds || []);
+  const sourceByGroupId = {};
+
+  safeRecords.forEach((record) => {
+    if (normalizeRecordPlatform(record, fallbackPlatform) !== 'twitch' || record?.hasVod !== true) return;
+    const recordId = normalizeId(record?.id);
+    const groupId = index.groupIdByRecordId[recordId];
+    if (!groupId || conflictGroupIds.has(groupId)) return;
+    const vodId = normalizeText(record?.vodId) || getFirstMatchingUrlValue(record, extractTwitchVodIdFromUrl);
+    if (!vodId) return;
+    const current = sourceByGroupId[groupId];
+    const currentScore = current
+      ? Number(Boolean(current.vodStartAt || current.vodPublishedAt)) +
+        Number(Number.isFinite(Number(current.vodTimeOffsetSeconds)))
+      : -1;
+    const nextScore = Number(Boolean(record.vodStartAt || record.vodPublishedAt)) +
+      Number(Number.isFinite(Number(record.vodTimeOffsetSeconds)));
+    if (!current || nextScore > currentScore) sourceByGroupId[groupId] = record;
+  });
+
+  const patches = [];
+  safeRecords.forEach((record) => {
+    const recordId = normalizeId(record?.id);
+    if (!recordId || normalizeRecordPlatform(record, fallbackPlatform) !== 'twitch' || record.hasVod === true) {
+      return;
+    }
+    const groupId = index.groupIdByRecordId[recordId];
+    if (!groupId || conflictGroupIds.has(groupId)) return;
+    const source = sourceByGroupId[groupId];
+    if (!source || recordHasConflictingIdentity(record, source)) return;
+    const vodId = normalizeText(source.vodId) || getFirstMatchingUrlValue(source, extractTwitchVodIdFromUrl);
+    if (!vodId) return;
+
+    const vodStartAt = source.vodStartAt || source.vodPublishedAt || null;
+    const vodStartMs = parseUtcMillis(vodStartAt);
+    const recordCreatedAtMs = parseUtcMillis(record.createdAt);
+    const configuredOffsetSeconds = Number.isFinite(Number(record.timeOffsetSeconds))
+      ? Math.max(0, Number(record.timeOffsetSeconds))
+      : 0;
+    const timestampOffsetSeconds = vodStartMs !== null && recordCreatedAtMs !== null &&
+      recordCreatedAtMs >= vodStartMs
+      ? Math.max(0, Math.floor((recordCreatedAtMs - vodStartMs) / 1000) - configuredOffsetSeconds)
+      : null;
+    const fallbackOffsetSeconds = parseElapsedSeconds(record.liveTime || record.originalLiveTime);
+    const vodTimeOffsetSeconds = timestampOffsetSeconds ?? fallbackOffsetSeconds;
+    const sourceVideoUrl = getRecordUrls(source).find((url) => extractTwitchVodIdFromUrl(url) === vodId) ||
+      `https://www.twitch.tv/videos/${vodId}`;
+    const vodMatchedBy = Array.from(new Set([
+      ...(Array.isArray(source.vodMatchedBy) ? source.vodMatchedBy : []),
+      'sibling-record'
+    ]));
+    const candidate = {
+      hasVod: true,
+      videoUrl: sourceVideoUrl,
+      vodId,
+      vodPublishedAt: source.vodPublishedAt || vodStartAt,
+      vodStartAt,
+      vodTitle: source.vodTitle || '',
+      vodLookupVersion: 2,
+      vodMatchedBy
+    };
+    if (Number.isFinite(vodTimeOffsetSeconds)) candidate.vodTimeOffsetSeconds = vodTimeOffsetSeconds;
+    if (Number.isFinite(Number(source.vodMatchConfidence))) {
+      candidate.vodMatchConfidence = Number(source.vodMatchConfidence);
+    }
+    if (source.downloadUrl) {
+      candidate.downloadUrl = source.downloadUrl;
+      candidate.isDirectM3u8 = source.isDirectM3u8 || false;
+      candidate.m3u8Type = source.m3u8Type || null;
+    }
+
+    const patch = {};
+    Object.entries(candidate).forEach(([field, value]) => {
+      if (!valuesEqual(record[field], value)) patch[field] = value;
+    });
+    if (Object.keys(patch).length === 0) return;
+    patches.push({
+      recordId,
+      patch,
+      operationId: buildRecordTimeLabelVodPatchOperationId(recordId, patch)
+    });
+  });
+
+  return {
+    patches,
+    diagnostics: {
+      sourceGroupCount: Object.keys(sourceByGroupId).length,
+      patchCount: patches.length,
+      skippedConflictGroupCount: conflictGroupIds.size
+    }
+  };
+};

package/src/domain.js

@@ -0,0 +1,45 @@
+export const RECORD_TIMELABEL_DOMAIN_CAPABILITIES = Object.freeze([
+  'group-identity-v1',
+  'twitch-vod-matching-v1',
+  'legacy-import-v1',
+  'channel-folder-planning-v1'
+]);
+
+export {
+  RECORD_GROUP_IDENTITY_VERSION,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  canonicalizeRecordTimeLabelGroupView
+} from './domain/group-identity.js';
+
+export {
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl
+} from './domain/shared.js';
+
+export {
+  buildKnownTwitchVodRecordPatches,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  normalizeVodTitleForMatch,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+} from './domain/twitch-vod.js';
+
+export {
+  normalizeLegacyRecordTimeLabelImport,
+  remapLegacyRecordTimeLabelFolderAliases
+} from './domain/legacy.js';
+
+export {
+  buildRecordTimeLabelChannelFolderPlan,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName
+} from './domain/channel-folder.js';

package/src/firestore-v2.js

@@ -21,6 +21,11 @@ export {
   buildRecordTimeLabelRequestId,
   buildOperationsFromSnapshotDiff,
   buildStateFromFirestoreV2Documents,
+  buildFirestoreV2SnapshotRoot,
+  applyRecordTimeLabelSnapshot,
+  composeRecordTimeLabelHydratedState,
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
   estimateFirestoreV2WriteUnits,
   createRecordTimeLabelTransportFailureResults,
   extendFirestoreV2OperationReadPlanWithRecords,

package/src/index.js

@@ -31,7 +31,85 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.7';
+import {
+  buildFirestoreV2SnapshotRoot,
+  isActiveLifecycleTombstone
+} from './snapshot-root.js';
+import {
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS
+} from './changefeed.js';
+
+export {
+  buildFirestoreV2SnapshotRoot,
+  compareLifecycleTombstones,
+  isActiveLifecycleTombstone,
+  mergeRootLifecycleTombstone,
+  mergeUniqueSnapshotIds,
+  stripSnapshotBulkStatus
+} from './snapshot-root.js';
+export {
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS
+} from './changefeed.js';
+
+import {
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildKnownTwitchVodRecordPatches,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelChannelFolderPlan,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  canonicalizeRecordTimeLabelGroupView,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
+  normalizeLegacyRecordTimeLabelImport,
+  normalizeVodTitleForMatch,
+  remapLegacyRecordTimeLabelFolderAliases,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+} from './domain.js';
+
+export {
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildKnownTwitchVodRecordPatches,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelChannelFolderPlan,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  canonicalizeRecordTimeLabelGroupView,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
+  normalizeLegacyRecordTimeLabelImport,
+  normalizeVodTitleForMatch,
+  remapLegacyRecordTimeLabelFolderAliases,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+};
+
+export const RECORD_TIMELABEL_CORE_VERSION = '0.6.0';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -2028,6 +2106,184 @@ export const buildStateFromFirestoreV2Documents = (documents = {}, options = {})
   return { state, pendingOps };
 };
 
+const collectActiveTombstoneIds = (state = {}, kind) => {
+  const rootField = kind === 'records' ? 'deletedRecordTombstones' : 'deletedFolderTombstones';
+  const blocked = new Set();
+  Object.entries(state?.[rootField] || {}).forEach(([id, tombstone]) => {
+    if (isActiveLifecycleTombstone(tombstone)) blocked.add(id);
+  });
+  Object.entries(state?.lifecycleTombstones || {}).forEach(([id, tombstone]) => {
+    if (!isActiveLifecycleTombstone(tombstone)) return;
+    const entityId = String(tombstone.entityId || id.split(':').slice(1).join(':') || '').trim();
+    const tombstoneKind = String(tombstone.kind || id.split(':')[0] || '').trim();
+    if (kind === 'records' && tombstoneKind === 'record' && entityId) blocked.add(entityId);
+    if (kind === 'folders' && tombstoneKind === 'folder' && entityId) blocked.add(entityId);
+  });
+  return blocked;
+};
+
+const mergeLifecycleTombstoneDocuments = (current = {}, incoming = {}) => {
+  const merged = {...(current || {})};
+  Object.entries(incoming || {}).forEach(([id, tombstone]) => {
+    const existing = merged[id];
+    if (!existing) {
+      merged[id] = tombstone;
+      return;
+    }
+    const currentGeneration = Number(existing.lifecycleGeneration || 0);
+    const nextGeneration = Number(tombstone?.lifecycleGeneration || 0);
+    const currentDeletedAt = Number(existing.deletedAt || 0);
+    const nextDeletedAt = Number(tombstone?.deletedAt || 0);
+    if (nextGeneration > currentGeneration ||
+      (nextGeneration === currentGeneration && nextDeletedAt >= currentDeletedAt)) {
+      merged[id] = tombstone;
+    }
+  });
+  return merged;
+};
+
+const collectDocumentIdChanges = (currentDocs = {}, nextDocs = {}) => {
+  const currentIds = new Set(Object.keys(currentDocs || {}));
+  const nextIds = new Set(Object.keys(nextDocs || {}));
+  return {
+    upsertIds: [...nextIds].filter((id) => (
+      JSON.stringify(currentDocs?.[id] || null) !== JSON.stringify(nextDocs?.[id] || null)
+    )).sort(),
+    deleteIds: [...currentIds].filter((id) => !nextIds.has(id)).sort()
+  };
+};
+
+export const applyRecordTimeLabelSnapshot = (
+  currentState = {},
+  incomingState = {},
+  mode = 'snapshot.replace'
+) => {
+  const snapshotMode = mode === 'snapshot.merge' ? 'snapshot.merge' : 'snapshot.replace';
+  const isMerge = snapshotMode === 'snapshot.merge';
+  const current = normalizeState(currentState || {});
+  const incoming = normalizeState(incomingState || {});
+  const currentDocs = buildFirestoreV2DocumentsFromState(current);
+  const incomingDocs = buildFirestoreV2DocumentsFromState(incoming);
+  const blockedRecordIds = collectActiveTombstoneIds(current, 'records');
+  const blockedFolderIds = collectActiveTombstoneIds(current, 'folders');
+
+  const mergedRecordDocs = {...(currentDocs.records || {})};
+  Object.entries(incomingDocs.records || {}).forEach(([id, data]) => {
+    if (blockedRecordIds.has(id)) return;
+    mergedRecordDocs[id] = data;
+  });
+  const recordDocs = isMerge
+    ? mergedRecordDocs
+    : Object.fromEntries(Object.entries(mergedRecordDocs).filter(([id]) => (
+      incomingDocs.records?.[id] && !blockedRecordIds.has(id)
+    )));
+
+  const mergedFolderDocs = {...(currentDocs.folders || {})};
+  Object.entries(incomingDocs.folders || {}).forEach(([id, data]) => {
+    if (blockedFolderIds.has(id)) return;
+    mergedFolderDocs[id] = data;
+  });
+  const folderDocs = isMerge
+    ? mergedFolderDocs
+    : Object.fromEntries(Object.entries(mergedFolderDocs).filter(([id]) => (
+      incomingDocs.folders?.[id] && !blockedFolderIds.has(id)
+    )));
+
+  const nextRoot = buildFirestoreV2SnapshotRoot({
+    currentRoot: currentDocs.root || {},
+    incomingRoot: incomingDocs.root || {},
+    mode: snapshotMode
+  });
+  const {state} = buildStateFromFirestoreV2Documents({
+    root: {id: 'main', ...nextRoot},
+    records: recordDocs,
+    folders: folderDocs,
+    trash: {...(currentDocs.trash || {})},
+    ops: {},
+    lifecycleTombstones: mergeLifecycleTombstoneDocuments(
+      currentDocs.lifecycleTombstones,
+      incomingDocs.lifecycleTombstones
+    )
+  });
+  const nextDocs = buildFirestoreV2DocumentsFromState(state);
+  const recordChanges = collectDocumentIdChanges(currentDocs.records, nextDocs.records);
+  const folderChanges = collectDocumentIdChanges(currentDocs.folders, nextDocs.folders);
+  return {
+    state: {...state, pendingOps: []},
+    documentChanges: {
+      records: recordChanges,
+      folders: folderChanges,
+      trash: {upsertIds: [], deleteIds: []},
+      root: true
+    },
+    diagnostics: {
+      mode: snapshotMode,
+      blockedRecordCount: blockedRecordIds.size,
+      blockedFolderCount: blockedFolderIds.size,
+      recordUpsertCount: recordChanges.upsertIds.length,
+      recordDeleteCount: recordChanges.deleteIds.length,
+      folderUpsertCount: folderChanges.upsertIds.length,
+      folderDeleteCount: folderChanges.deleteIds.length,
+      trashPreserved: true
+    }
+  };
+};
+
+export const composeRecordTimeLabelHydratedState = ({
+  remote = {},
+  pendingOps = [],
+  importJobs = [],
+  localNavigation = null
+} = {}) => {
+  const jobs = (Array.isArray(importJobs) ? importJobs : [])
+    .filter((job) => job && typeof job === 'object')
+    .sort((left, right) => Number(left?.createdAt || 0) - Number(right?.createdAt || 0));
+  const coveredOperationIds = new Set();
+  let state = normalizeState(remote || {});
+  jobs.forEach((job) => {
+    state = applyRecordTimeLabelSnapshot(
+      state,
+      job.state || {},
+      job.mode === 'snapshot.merge' ? 'snapshot.merge' : 'snapshot.replace'
+    ).state;
+    (Array.isArray(job.includedOperationIds) ? job.includedOperationIds : []).forEach((id) => {
+      if (id) coveredOperationIds.add(id);
+    });
+  });
+  (Array.isArray(pendingOps) ? pendingOps : [])
+    .filter((operation) => operation?.id && !coveredOperationIds.has(operation.id))
+    .forEach((operation) => {
+      state = applyRecordTimeLabelOperation(state, operation);
+    });
+
+  const navigation = localNavigation && typeof localNavigation === 'object' ? localNavigation : {};
+  const nextSettings = {...(state.settings || {})};
+  const lastActiveFolderId = navigation.lastActiveFolderId;
+  if (lastActiveFolderId) {
+    const folderExists = (Array.isArray(state.folders) ? state.folders : [])
+      .some((folder) => folder?.id === lastActiveFolderId);
+    if (folderExists) nextSettings.lastActiveFolderId = lastActiveFolderId;
+    else delete nextSettings.lastActiveFolderId;
+  } else {
+    delete nextSettings.lastActiveFolderId;
+  }
+  const localExpandedGroups = Array.isArray(navigation.expandedGroups) ? navigation.expandedGroups : [];
+  const expandedGroups = Array.from(new Set([
+    ...(Array.isArray(state.expandedGroups) ? state.expandedGroups : []),
+    ...localExpandedGroups
+  ]));
+  const remoteRevision = Number(remote?.revision);
+  return {
+    state: {
+      ...state,
+      settings: nextSettings,
+      expandedGroups,
+      ...(Number.isFinite(remoteRevision) ? {revision: remoteRevision} : {})
+    },
+    coveredOperationIds: Array.from(coveredOperationIds)
+  };
+};
+
 const mergeOrderArrays = (normalizer, ...orders) => {
   const seen = new Set();
   const result = [];
@@ -5289,6 +5545,8 @@ export const buildOperationsFromSnapshotDiff = ({
 
 export default {
   RECORD_TIMELABEL_CORE_VERSION,
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
   RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
@@ -5330,6 +5588,11 @@ export default {
   buildFirestoreV2DocumentsFromState,
   buildFirestoreV2DocumentChangeSet,
   buildStateFromFirestoreV2Documents,
+  buildFirestoreV2SnapshotRoot,
+  applyRecordTimeLabelSnapshot,
+  composeRecordTimeLabelHydratedState,
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
   validateRecordTimeLabelOperationBatch,
   buildFirestoreV2OperationReadPlan,
   extendFirestoreV2OperationReadPlanWithRecords,