@recordtimelabel/core 0.5.0 → 0.6.1

package/README.md

@@ -17,10 +17,10 @@ During local development an app can consume a sibling checkout with:
 "@recordtimelabel/core": "file:../recordtimelabel-core"
 ```
 
-For release builds, consume a fixed npm package, git tag, or private registry version so builds do not depend on a sibling folder path. The current strict durable transport contract is prepared in package version `0.4.6` (publish it before updating consumers):
+For release builds, consume a fixed npm package, git tag, or private registry version so builds do not depend on a sibling folder path. The current published artifact is `0.6.1`:
 
 ```json
-"@recordtimelabel/core": "0.4.6"
+"@recordtimelabel/core": "0.6.1"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -74,6 +74,11 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `OPERATION_TYPES`
 - `getActiveTrashEntries(entries, now)`
 - `RTL_TRASH_RETENTION_MS`
+- `buildFirestoreV2SnapshotRoot({ currentRoot, incomingRoot, mode })`
+- `applyRecordTimeLabelSnapshot(currentState, incomingState, mode)`
+- `composeRecordTimeLabelHydratedState({ remote, pendingOps, importJobs, localNavigation })`
+- `applyFirestoreV2ResolvedChangeBatch({ cache, changes, resolvedDocuments, targetRevision })`
+- `FIRESTORE_V2_BOOTSTRAP_REASONS`
 
 The package exports five intentional entrypoints. The root (`@recordtimelabel/core`)
 keeps the complete backwards-compatible surface, `/protocol` contains only shared

package/package.json

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

package/src/changefeed.js

@@ -0,0 +1,231 @@
+export const FIRESTORE_V2_BOOTSTRAP_REASONS = Object.freeze({
+  REVISION_GAP: 'revision-gap',
+  REVISION_DUPLICATE: 'revision-duplicate',
+  REVISION_OVERSHOOT: 'revision-overshoot',
+  CACHE_AHEAD: 'cache-ahead',
+  CHANGED_DOCUMENT_MISSING: 'changed-document-missing',
+  ROOT_DOCUMENT_MISSING: 'root-document-missing',
+  INVALID_CHANGE_CONFLICT: 'invalid-change-conflict'
+});
+
+const toId = (value) => String(value || '').trim();
+const toIdList = (value) => (Array.isArray(value) ? value : []).map(toId).filter(Boolean);
+
+const decodeLifecycleTombstoneId = (value) => {
+  const id = toId(value);
+  if (!id) return '';
+  try {
+    return decodeURIComponent(id);
+  } catch {
+    return id;
+  }
+};
+
+export const lifecycleTombstoneDocumentKey = (value) => {
+  const logicalId = decodeLifecycleTombstoneId(value);
+  return logicalId ? encodeURIComponent(logicalId) : '';
+};
+
+export const lifecycleTombstoneKeyAliases = (value) => {
+  const logicalId = decodeLifecycleTombstoneId(value);
+  if (!logicalId) return [];
+  return [...new Set([toId(value), logicalId, encodeURIComponent(logicalId)].filter(Boolean))];
+};
+
+const cloneDocuments = (documents = {}) => ({
+  root: documents.root ? {...documents.root} : documents.root,
+  records: {...(documents.records || {})},
+  folders: {...(documents.folders || {})},
+  trash: {...(documents.trash || {})},
+  lifecycleTombstones: {...(documents.lifecycleTombstones || {})},
+  ops: {...(documents.ops || {})}
+});
+
+const fail = (reason, inputCache) => ({
+  ok: false,
+  bootstrapRequired: true,
+  reason,
+  cache: {
+    revision: Number(inputCache?.revision || 0),
+    documents: cloneDocuments(inputCache?.documents || {})
+  },
+  diagnostics: {reason, appliedCount: 0}
+});
+
+const hasConflict = (changedIds, deletedIds) => {
+  const deleted = new Set(deletedIds);
+  return changedIds.some((id) => deleted.has(id));
+};
+
+const resolvedDocument = (resolvedDocuments, kind, id) => {
+  const bucket = resolvedDocuments?.[kind];
+  if (!bucket || !Object.prototype.hasOwnProperty.call(bucket, id)) return undefined;
+  return bucket[id];
+};
+
+export const applyFirestoreV2ResolvedChangeBatch = ({
+  cache = {},
+  changes = [],
+  resolvedDocuments = {},
+  targetRevision = null
+} = {}) => {
+  const inputRevision = Number(cache?.revision || 0);
+  const inputDocuments = cache?.documents || {};
+  const inputCache = {revision: inputRevision, documents: inputDocuments};
+  const expectedTarget = targetRevision == null ? null : Number(targetRevision);
+  if (!Number.isFinite(inputRevision) || inputRevision < 0) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
+  }
+
+  const batch = Array.isArray(changes) ? changes : [];
+  if (batch.length === 0) {
+    if (expectedTarget != null && Number.isFinite(expectedTarget) && expectedTarget < inputRevision) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.CACHE_AHEAD, inputCache);
+    }
+    return {
+      ok: true,
+      bootstrapRequired: false,
+      reason: null,
+      cache: {revision: inputRevision, documents: cloneDocuments(inputDocuments)},
+      diagnostics: {reason: null, appliedCount: 0}
+    };
+  }
+
+  const firstRevision = Number(batch[0]?.revision || 0);
+  if (expectedTarget != null && Number.isFinite(expectedTarget) && inputRevision > expectedTarget) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.CACHE_AHEAD, inputCache);
+  }
+  if (firstRevision <= inputRevision) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_DUPLICATE, inputCache);
+  }
+  if (expectedTarget != null && Number.isFinite(expectedTarget) && firstRevision > expectedTarget) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
+  }
+  if (firstRevision > inputRevision + 1) {
+    return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP, inputCache);
+  }
+
+  const candidate = {
+    revision: inputRevision,
+    documents: cloneDocuments(inputDocuments)
+  };
+  let rootChanged = false;
+
+  for (let index = 0; index < batch.length; index += 1) {
+    const change = batch[index] || {};
+    const revision = Number(change.revision || 0);
+    if (revision !== candidate.revision + 1) {
+      const reason = revision <= candidate.revision
+        ? FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_DUPLICATE
+        : FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_GAP;
+      return fail(reason, inputCache);
+    }
+    if (expectedTarget != null && Number.isFinite(expectedTarget) && revision > expectedTarget) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
+    }
+
+    const changedRecords = toIdList(change.changedRecordIds);
+    const deletedRecords = toIdList(change.deletedRecordIds);
+    const changedFolders = toIdList(change.changedFolderIds);
+    const deletedFolders = toIdList(change.deletedFolderIds);
+    const changedTrash = toIdList(change.changedTrashEntryIds);
+    const deletedTrash = toIdList(change.deletedTrashEntryIds);
+    const lifecycleUpserts = Array.isArray(change.lifecycleTombstoneUpserts)
+      ? change.lifecycleTombstoneUpserts
+      : [];
+    const lifecycleDeletes = toIdList(change.deletedLifecycleTombstoneIds);
+    const lifecycleUpsertIds = lifecycleUpserts
+      .map((entry) => lifecycleTombstoneDocumentKey(entry?.id))
+      .filter(Boolean);
+    const lifecycleDeleteIds = lifecycleDeletes
+      .map((id) => lifecycleTombstoneDocumentKey(id))
+      .filter(Boolean);
+
+    if (
+      hasConflict(changedRecords, deletedRecords) ||
+      hasConflict(changedFolders, deletedFolders) ||
+      hasConflict(changedTrash, deletedTrash) ||
+      hasConflict(lifecycleUpsertIds, lifecycleDeleteIds)
+    ) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.INVALID_CHANGE_CONFLICT, inputCache);
+    }
+
+    const missingChanged = [
+      ...changedRecords.map((id) => ['records', id]),
+      ...changedFolders.map((id) => ['folders', id]),
+      ...changedTrash.map((id) => ['trash', id])
+    ].some(([kind, id]) => {
+      const document = resolvedDocument(resolvedDocuments, kind, id);
+      return document == null;
+    });
+    if (missingChanged) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.CHANGED_DOCUMENT_MISSING, inputCache);
+    }
+
+    if (change.rootChanged === true) {
+      const rootDocument = resolvedDocuments.root;
+      const rootRevision = Number(rootDocument?.revision || 0);
+      if (!rootDocument || !Number.isFinite(rootRevision) || rootRevision < revision) {
+        return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.ROOT_DOCUMENT_MISSING, inputCache);
+      }
+      rootChanged = true;
+    }
+
+    changedRecords.forEach((id) => {
+      const document = resolvedDocument(resolvedDocuments, 'records', id);
+      candidate.documents.records[id] = {id, ...document};
+    });
+    changedFolders.forEach((id) => {
+      const document = resolvedDocument(resolvedDocuments, 'folders', id);
+      candidate.documents.folders[id] = {id, ...document};
+    });
+    changedTrash.forEach((id) => {
+      const document = resolvedDocument(resolvedDocuments, 'trash', id);
+      candidate.documents.trash[id] = {id, ...document};
+    });
+    deletedRecords.forEach((id) => delete candidate.documents.records[id]);
+    deletedFolders.forEach((id) => delete candidate.documents.folders[id]);
+    deletedTrash.forEach((id) => delete candidate.documents.trash[id]);
+    lifecycleUpserts.forEach((entry) => {
+      const logicalId = decodeLifecycleTombstoneId(entry?.id);
+      const documentKey = lifecycleTombstoneDocumentKey(logicalId);
+      if (!documentKey) return;
+      lifecycleTombstoneKeyAliases(logicalId).forEach((alias) => {
+        delete candidate.documents.lifecycleTombstones[alias];
+      });
+      candidate.documents.lifecycleTombstones[documentKey] = {
+        ...entry,
+        id: logicalId
+      };
+    });
+    lifecycleDeletes.forEach((id) => {
+      lifecycleTombstoneKeyAliases(id).forEach((alias) => {
+        delete candidate.documents.lifecycleTombstones[alias];
+      });
+    });
+    candidate.revision = revision;
+  }
+
+  if (rootChanged) {
+    const rootDocument = resolvedDocuments.root;
+    candidate.documents.root = {id: 'main', ...rootDocument};
+  } else if (candidate.documents.root) {
+    candidate.documents.root = {
+      ...candidate.documents.root,
+      id: 'main',
+      revision: candidate.revision
+    };
+  }
+
+  return {
+    ok: true,
+    bootstrapRequired: false,
+    reason: null,
+    cache: candidate,
+    diagnostics: {
+      reason: null,
+      appliedCount: batch.length,
+      revision: candidate.revision
+    }
+  };
+};

package/src/domain/group-identity.js

@@ -1,4 +1,7 @@
-import {fingerprintCanonicalJson} from './hash.js';
+import {
+  createdAtForStableRecordTimeLabelOperationId,
+  fingerprintCanonicalJson
+} from './hash.js';
 import {
   DEFAULT_UNKNOWN_CHANNEL,
   DEFAULT_UNKNOWN_TITLE,
@@ -309,6 +312,26 @@ export const buildRecordTimeLabelGroupIndex = ({
     );
     addAliasTarget(aliasTargetsByGroupId, buildLegacyRecordTimeLabelGroupId(record, platform, unknownTitle), groupId);
     addAliasTarget(aliasTargetsByGroupId, buildFallbackRecordGroupId(record, platform, unknownTitle), groupId);
+    const declaredPlatform = normalizeText(record?.platform).toLowerCase();
+    if (declaredPlatform !== 'twitch' && declaredPlatform !== 'youtube') {
+      ['twitch', 'youtube'].forEach((themePlatform) => {
+        addAliasTarget(
+          aliasTargetsByGroupId,
+          buildLegacyRecordTimeLabelGroupId(record, themePlatform, unknownTitle),
+          groupId
+        );
+        addAliasTarget(
+          aliasTargetsByGroupId,
+          buildFallbackRecordGroupId(record, themePlatform, unknownTitle),
+          groupId
+        );
+        addAliasTarget(
+          aliasTargetsByGroupId,
+          buildRecordTimeLabelStandaloneGroupId(record, themePlatform, unknownTitle),
+          groupId
+        );
+      });
+    }
   });
 
   const groups = Object.values(groupsById).sort((left, right) => {
@@ -454,3 +477,17 @@ export const buildRecordTimeLabelGroupMetadata = ({
 export const buildRecordTimeLabelGroupReorderOperationId = (previousOrder = [], nextOrder = []) => (
   `group.reorder:canonical:${fingerprintCanonicalJson(normalizeIdList(previousOrder))}:${fingerprintCanonicalJson(normalizeIdList(nextOrder))}`
 );
+
+export const buildRecordTimeLabelGroupReorderOperation = ({
+  previousOrder = [],
+  nextOrder = []
+} = {}) => {
+  const groupOrder = normalizeIdList(nextOrder);
+  const id = buildRecordTimeLabelGroupReorderOperationId(previousOrder, groupOrder);
+  return {
+    id,
+    type: 'group.reorder',
+    createdAt: createdAtForStableRecordTimeLabelOperationId(id),
+    payload: {groupOrder}
+  };
+};

package/src/domain/hash.js

@@ -145,3 +145,9 @@ export const digestCanonicalJson = (value) => sha256Hex(canonicalizeJson(value))
 export const fingerprintCanonicalJson = (value, length = 16) => (
   digestCanonicalJson(value).slice(0, length)
 );
+
+export const createdAtForStableRecordTimeLabelOperationId = (operationId) => {
+  const digest = digestCanonicalJson(String(operationId || ''));
+  const value = Number.parseInt(digest.slice(0, 12), 16);
+  return Number.isSafeInteger(value) && value > 0 ? value : 1;
+};

package/src/domain/twitch-vod.js

@@ -1,4 +1,7 @@
-import {fingerprintCanonicalJson} from './hash.js';
+import {
+  createdAtForStableRecordTimeLabelOperationId,
+  fingerprintCanonicalJson
+} from './hash.js';
 import {buildRecordTimeLabelGroupIndex} from './group-identity.js';
 import {
   DEFAULT_UNKNOWN_TITLE,
@@ -197,6 +200,22 @@ export const buildRecordTimeLabelVodPatchOperationId = (recordId, patch = {}) =>
   `record.update:${normalizeId(recordId)}:vod-patch:${fingerprintCanonicalJson(patch || {})}`
 );
 
+export const buildRecordTimeLabelVodPatchOperation = ({recordId, patch = {}} = {}) => {
+  const safePatch = {...(patch || {})};
+  delete safePatch.updatedAt;
+  const id = buildRecordTimeLabelVodPatchOperationId(recordId, safePatch);
+  const createdAt = createdAtForStableRecordTimeLabelOperationId(id);
+  return {
+    id,
+    type: 'record.update',
+    createdAt,
+    payload: {
+      recordId: normalizeId(recordId),
+      patch: {...safePatch, updatedAt: createdAt}
+    }
+  };
+};
+
 export const buildKnownTwitchVodRecordPatches = ({
   records = [],
   groupIndex = null,

package/src/domain.js

@@ -10,11 +10,16 @@ export {
   buildLegacyRecordTimeLabelGroupId,
   buildRecordTimeLabelGroupIndex,
   buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperation,
   buildRecordTimeLabelGroupReorderOperationId,
   buildRecordTimeLabelStandaloneGroupId,
   canonicalizeRecordTimeLabelGroupView
 } from './domain/group-identity.js';
 
+export {
+  createdAtForStableRecordTimeLabelOperationId
+} from './domain/hash.js';
+
 export {
   extractTwitchVodIdFromUrl,
   extractYouTubeVideoIdFromUrl
@@ -22,6 +27,7 @@ export {
 
 export {
   buildKnownTwitchVodRecordPatches,
+  buildRecordTimeLabelVodPatchOperation,
   buildRecordTimeLabelVodPatchOperationId,
   calculateVodTitleSimilarity,
   normalizeVodTitleForMatch,

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,6 +31,32 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
+import {
+  buildFirestoreV2SnapshotRoot,
+  isActiveLifecycleTombstone
+} from './snapshot-root.js';
+import {
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
+  lifecycleTombstoneDocumentKey,
+  lifecycleTombstoneKeyAliases
+} from './changefeed.js';
+
+export {
+  buildFirestoreV2SnapshotRoot,
+  compareLifecycleTombstones,
+  isActiveLifecycleTombstone,
+  mergeRootLifecycleTombstone,
+  mergeUniqueSnapshotIds,
+  stripSnapshotBulkStatus
+} from './snapshot-root.js';
+export {
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
+  lifecycleTombstoneDocumentKey,
+  lifecycleTombstoneKeyAliases
+} from './changefeed.js';
+
 import {
   RECORD_GROUP_IDENTITY_VERSION,
   RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
@@ -39,11 +65,14 @@ import {
   buildRecordTimeLabelChannelFolderPlan,
   buildRecordTimeLabelGroupIndex,
   buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperation,
   buildRecordTimeLabelGroupReorderOperationId,
   buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperation,
   buildRecordTimeLabelVodPatchOperationId,
   calculateVodTitleSimilarity,
   canonicalizeRecordTimeLabelGroupView,
+  createdAtForStableRecordTimeLabelOperationId,
   collectRecordTimeLabelChannelCandidates,
   extractChannelHandleFromUrl,
   extractTwitchVodIdFromUrl,
@@ -67,11 +96,14 @@ export {
   buildRecordTimeLabelChannelFolderPlan,
   buildRecordTimeLabelGroupIndex,
   buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperation,
   buildRecordTimeLabelGroupReorderOperationId,
   buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperation,
   buildRecordTimeLabelVodPatchOperationId,
   calculateVodTitleSimilarity,
   canonicalizeRecordTimeLabelGroupView,
+  createdAtForStableRecordTimeLabelOperationId,
   collectRecordTimeLabelChannelCandidates,
   extractChannelHandleFromUrl,
   extractTwitchVodIdFromUrl,
@@ -87,7 +119,7 @@ export {
   selectBestMatchingTwitchVod
 };
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.5.0';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.6.1';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -2084,6 +2116,264 @@ 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 = {};
+  const writeTombstone = (rawId, tombstone) => {
+    const documentKey = lifecycleTombstoneDocumentKey(rawId || tombstone?.id);
+    if (!documentKey || !tombstone) return;
+    const logicalId = decodeURIComponent(documentKey);
+    lifecycleTombstoneKeyAliases(logicalId).forEach((alias) => {
+      delete merged[alias];
+    });
+    const existing = merged[documentKey];
+    const nextTombstone = {...tombstone, id: logicalId};
+    if (!existing) {
+      merged[documentKey] = nextTombstone;
+      return;
+    }
+    const currentGeneration = Number(existing.lifecycleGeneration || 0);
+    const nextGeneration = Number(nextTombstone.lifecycleGeneration || 0);
+    const currentDeletedAt = Number(existing.deletedAt || 0);
+    const nextDeletedAt = Number(nextTombstone.deletedAt || 0);
+    if (nextGeneration > currentGeneration ||
+      (nextGeneration === currentGeneration && nextDeletedAt >= currentDeletedAt)) {
+      merged[documentKey] = nextTombstone;
+    } else {
+      merged[documentKey] = existing;
+    }
+  };
+  Object.entries(current || {}).forEach(([id, tombstone]) => writeTombstone(id, tombstone));
+  Object.entries(incoming || {}).forEach(([id, tombstone]) => writeTombstone(id, tombstone));
+  return merged;
+};
+
+const pickNewerLifecycleEntity = (left, right, getTime) => {
+  if (!left) return right;
+  if (!right) return left;
+  const leftGeneration = Number(left.lifecycleGeneration || 0);
+  const rightGeneration = Number(right.lifecycleGeneration || 0);
+  if (leftGeneration !== rightGeneration) {
+    return rightGeneration > leftGeneration ? right : left;
+  }
+  return getTime(right) >= getTime(left) ? right : left;
+};
+
+const tombstoneBlocksEntity = (tombstone, entity, getTime) => {
+  if (!isActiveLifecycleTombstone(tombstone)) return false;
+  if (!entity) return true;
+  const tombstoneGeneration = Number(tombstone.lifecycleGeneration || 0);
+  const entityGeneration = Number(entity.lifecycleGeneration || 0);
+  if (entityGeneration !== tombstoneGeneration) {
+    return tombstoneGeneration > entityGeneration;
+  }
+  return toFiniteTimestamp(tombstone.deletedAt) >= getTime(entity);
+};
+
+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 mergedTombstoneDocs = mergeLifecycleTombstoneDocuments(
+    currentDocs.lifecycleTombstones,
+    incomingDocs.lifecycleTombstones
+  );
+  const splitTombstones = splitLifecycleTombstoneDocuments(mergedTombstoneDocs);
+  const mergedRecordTombstones = mergeLifecycleTombstoneSources(
+    current.deletedRecordTombstones,
+    mergeLifecycleTombstoneSources(incoming.deletedRecordTombstones, splitTombstones.records)
+  );
+  const mergedFolderTombstones = mergeLifecycleTombstoneSources(
+    current.deletedFolderTombstones,
+    mergeLifecycleTombstoneSources(incoming.deletedFolderTombstones, splitTombstones.folders)
+  );
+  const remainingTombstones = dropSupersededLifecycleDeletions({
+    deletedRecordTombstones: mergedRecordTombstones,
+    deletedFolderTombstones: mergedFolderTombstones,
+    trashEntries: {},
+    activeGenerations: collectActiveLifecycleStates(
+      ...(isMerge ? [current, incoming] : [incoming])
+    )
+  });
+
+  const selectRecordDocs = (currentRecordDocs, incomingRecordDocs) => {
+    const sourceIds = isMerge
+      ? new Set([...Object.keys(currentRecordDocs || {}), ...Object.keys(incomingRecordDocs || {})])
+      : new Set(Object.keys(incomingRecordDocs || {}));
+    const nextDocs = {};
+    sourceIds.forEach((id) => {
+      const entity = isMerge
+        ? pickNewerLifecycleEntity(currentRecordDocs?.[id], incomingRecordDocs?.[id], getRecordTime)
+        : incomingRecordDocs?.[id];
+      if (!entity || tombstoneBlocksEntity(remainingTombstones.deletedRecordTombstones[id], entity, getRecordTime)) {
+        return;
+      }
+      nextDocs[id] = entity;
+    });
+    return nextDocs;
+  };
+  const selectFolderDocs = (currentFolderDocs, incomingFolderDocs) => {
+    const sourceIds = isMerge
+      ? new Set([...Object.keys(currentFolderDocs || {}), ...Object.keys(incomingFolderDocs || {})])
+      : new Set(Object.keys(incomingFolderDocs || {}));
+    const nextDocs = {};
+    sourceIds.forEach((id) => {
+      const entity = isMerge
+        ? pickNewerLifecycleEntity(currentFolderDocs?.[id], incomingFolderDocs?.[id], getFolderTime)
+        : incomingFolderDocs?.[id];
+      if (!entity || tombstoneBlocksEntity(remainingTombstones.deletedFolderTombstones[id], entity, getFolderTime)) {
+        return;
+      }
+      nextDocs[id] = entity;
+    });
+    return nextDocs;
+  };
+
+  const recordDocs = selectRecordDocs(currentDocs.records, incomingDocs.records);
+  const folderDocs = selectFolderDocs(currentDocs.folders, incomingDocs.folders);
+  const blockedRecordIds = new Set(
+    Object.keys(remainingTombstones.deletedRecordTombstones || {}).filter((id) => (
+      isActiveLifecycleTombstone(remainingTombstones.deletedRecordTombstones[id]) && !recordDocs[id]
+    ))
+  );
+  const blockedFolderIds = new Set(
+    Object.keys(remainingTombstones.deletedFolderTombstones || {}).filter((id) => (
+      isActiveLifecycleTombstone(remainingTombstones.deletedFolderTombstones[id]) && !folderDocs[id]
+    ))
+  );
+
+  const nextRoot = {
+    ...buildFirestoreV2SnapshotRoot({
+      currentRoot: currentDocs.root || {},
+      incomingRoot: incomingDocs.root || {},
+      mode: snapshotMode
+    }),
+    deletedRecordTombstones: remainingTombstones.deletedRecordTombstones,
+    deletedFolderTombstones: remainingTombstones.deletedFolderTombstones
+  };
+  const {state} = buildStateFromFirestoreV2Documents({
+    root: {id: 'main', ...nextRoot},
+    records: recordDocs,
+    folders: folderDocs,
+    trash: {...(currentDocs.trash || {})},
+    ops: {},
+    lifecycleTombstones: buildV2LifecycleTombstoneDocuments(
+      remainingTombstones.deletedRecordTombstones,
+      remainingTombstones.deletedFolderTombstones
+    )
+  });
+  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 = [];
@@ -5347,6 +5637,32 @@ export default {
   RECORD_TIMELABEL_CORE_VERSION,
   RECORD_GROUP_IDENTITY_VERSION,
   RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperation,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  canonicalizeRecordTimeLabelGroupView,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  buildKnownTwitchVodRecordPatches,
+  buildRecordTimeLabelVodPatchOperation,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  normalizeVodTitleForMatch,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod,
+  normalizeLegacyRecordTimeLabelImport,
+  remapLegacyRecordTimeLabelFolderAliases,
+  buildRecordTimeLabelChannelFolderPlan,
+  collectRecordTimeLabelChannelCandidates,
+  createdAtForStableRecordTimeLabelOperationId,
+  extractChannelHandleFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
   RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
@@ -5388,6 +5704,11 @@ export default {
   buildFirestoreV2DocumentsFromState,
   buildFirestoreV2DocumentChangeSet,
   buildStateFromFirestoreV2Documents,
+  buildFirestoreV2SnapshotRoot,
+  applyRecordTimeLabelSnapshot,
+  composeRecordTimeLabelHydratedState,
+  applyFirestoreV2ResolvedChangeBatch,
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
   validateRecordTimeLabelOperationBatch,
   buildFirestoreV2OperationReadPlan,
   extendFirestoreV2OperationReadPlanWithRecords,

package/src/snapshot-root.js

@@ -0,0 +1,92 @@
+const toId = (value) => String(value || '').trim();
+
+export const mergeUniqueSnapshotIds = (...lists) => {
+  const seen = new Set();
+  return lists.flatMap((list) => (Array.isArray(list) ? list : []))
+    .filter((id) => {
+      const value = toId(id);
+      if (!value || seen.has(value)) return false;
+      seen.add(value);
+      return true;
+    });
+};
+
+export const stripSnapshotBulkStatus = (root = {}) => {
+  const stableRoot = {...(root || {})};
+  delete stableRoot.bulkStatus;
+  return stableRoot;
+};
+
+const toFiniteTimestamp = (value) => {
+  const timestamp = Number(value);
+  return Number.isFinite(timestamp) ? timestamp : 0;
+};
+
+const tombstoneGeneration = (value) => {
+  const generation = Number(value?.lifecycleGeneration || 0);
+  return Number.isFinite(generation) ? generation : 0;
+};
+
+export const compareLifecycleTombstones = (left = {}, right = {}) => {
+  const generationDelta = tombstoneGeneration(left) - tombstoneGeneration(right);
+  if (generationDelta !== 0) return generationDelta;
+  return toFiniteTimestamp(left.deletedAt) - toFiniteTimestamp(right.deletedAt);
+};
+
+export const mergeRootLifecycleTombstone = (current, incoming) => {
+  if (current == null) return incoming;
+  if (incoming == null) return current;
+  return compareLifecycleTombstones(incoming, current) >= 0 ? incoming : current;
+};
+
+export const isActiveLifecycleTombstone = (value) => (
+  tombstoneGeneration(value) > 0 && toFiniteTimestamp(value?.deletedAt) > 0
+);
+
+const mergeTombstoneMap = (current = {}, incoming = {}) => {
+  const result = {};
+  Object.keys(current || {}).forEach((id) => {
+    result[id] = current[id];
+  });
+  Object.keys(incoming || {}).forEach((id) => {
+    result[id] = mergeRootLifecycleTombstone(current?.[id], incoming[id]);
+  });
+  return result;
+};
+
+export const buildFirestoreV2SnapshotRoot = ({
+  currentRoot = {},
+  incomingRoot = {},
+  mode = 'snapshot.replace'
+} = {}) => {
+  const current = stripSnapshotBulkStatus(currentRoot);
+  const incoming = stripSnapshotBulkStatus(incomingRoot);
+  const isMerge = mode === 'snapshot.merge';
+  if (isMerge) {
+    return {
+      ...current,
+      ...incoming,
+      folderOrder: mergeUniqueSnapshotIds(incoming.folderOrder, current.folderOrder),
+      groupOrder: mergeUniqueSnapshotIds(incoming.groupOrder, current.groupOrder),
+      deletedRecordTombstones: mergeTombstoneMap(
+        current.deletedRecordTombstones,
+        incoming.deletedRecordTombstones
+      ),
+      deletedFolderTombstones: mergeTombstoneMap(
+        current.deletedFolderTombstones,
+        incoming.deletedFolderTombstones
+      )
+    };
+  }
+  return {
+    ...incoming,
+    deletedRecordTombstones: mergeTombstoneMap(
+      current.deletedRecordTombstones,
+      incoming.deletedRecordTombstones
+    ),
+    deletedFolderTombstones: mergeTombstoneMap(
+      current.deletedFolderTombstones,
+      incoming.deletedFolderTombstones
+    )
+  };
+};