@recordtimelabel/core 0.6.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 published artifact is `0.6.0`:
+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.6.0"
+"@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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.6.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

@@ -11,6 +11,27 @@ export const FIRESTORE_V2_BOOTSTRAP_REASONS = Object.freeze({
 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 || {})},
@@ -113,13 +134,18 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
       ? change.lifecycleTombstoneUpserts
       : [];
     const lifecycleDeletes = toIdList(change.deletedLifecycleTombstoneIds);
-    const lifecycleUpsertIds = lifecycleUpserts.map((entry) => toId(entry?.id)).filter(Boolean);
+    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, lifecycleDeletes)
+      hasConflict(lifecycleUpsertIds, lifecycleDeleteIds)
     ) {
       return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.INVALID_CHANGE_CONFLICT, inputCache);
     }
@@ -161,11 +187,21 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
     deletedFolders.forEach((id) => delete candidate.documents.folders[id]);
     deletedTrash.forEach((id) => delete candidate.documents.trash[id]);
     lifecycleUpserts.forEach((entry) => {
-      const id = toId(entry?.id);
-      if (id) candidate.documents.lifecycleTombstones[id] = {...entry, id};
+      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) => {
-      delete candidate.documents.lifecycleTombstones[id];
+      lifecycleTombstoneKeyAliases(id).forEach((alias) => {
+        delete candidate.documents.lifecycleTombstones[alias];
+      });
     });
     candidate.revision = 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/index.js

@@ -37,7 +37,9 @@ import {
 } from './snapshot-root.js';
 import {
   applyFirestoreV2ResolvedChangeBatch,
-  FIRESTORE_V2_BOOTSTRAP_REASONS
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
+  lifecycleTombstoneDocumentKey,
+  lifecycleTombstoneKeyAliases
 } from './changefeed.js';
 
 export {
@@ -50,7 +52,9 @@ export {
 } from './snapshot-root.js';
 export {
   applyFirestoreV2ResolvedChangeBatch,
-  FIRESTORE_V2_BOOTSTRAP_REASONS
+  FIRESTORE_V2_BOOTSTRAP_REASONS,
+  lifecycleTombstoneDocumentKey,
+  lifecycleTombstoneKeyAliases
 } from './changefeed.js';
 
 import {
@@ -61,11 +65,14 @@ import {
   buildRecordTimeLabelChannelFolderPlan,
   buildRecordTimeLabelGroupIndex,
   buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperation,
   buildRecordTimeLabelGroupReorderOperationId,
   buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperation,
   buildRecordTimeLabelVodPatchOperationId,
   calculateVodTitleSimilarity,
   canonicalizeRecordTimeLabelGroupView,
+  createdAtForStableRecordTimeLabelOperationId,
   collectRecordTimeLabelChannelCandidates,
   extractChannelHandleFromUrl,
   extractTwitchVodIdFromUrl,
@@ -89,11 +96,14 @@ export {
   buildRecordTimeLabelChannelFolderPlan,
   buildRecordTimeLabelGroupIndex,
   buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperation,
   buildRecordTimeLabelGroupReorderOperationId,
   buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperation,
   buildRecordTimeLabelVodPatchOperationId,
   calculateVodTitleSimilarity,
   canonicalizeRecordTimeLabelGroupView,
+  createdAtForStableRecordTimeLabelOperationId,
   collectRecordTimeLabelChannelCandidates,
   extractChannelHandleFromUrl,
   extractTwitchVodIdFromUrl,
@@ -109,7 +119,7 @@ export {
   selectBestMatchingTwitchVod
 };
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.6.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',
@@ -2123,25 +2133,58 @@ const collectActiveTombstoneIds = (state = {}, kind) => {
 };
 
 const mergeLifecycleTombstoneDocuments = (current = {}, incoming = {}) => {
-  const merged = {...(current || {})};
-  Object.entries(incoming || {}).forEach(([id, tombstone]) => {
-    const existing = merged[id];
+  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[id] = tombstone;
+      merged[documentKey] = nextTombstone;
       return;
     }
     const currentGeneration = Number(existing.lifecycleGeneration || 0);
-    const nextGeneration = Number(tombstone?.lifecycleGeneration || 0);
+    const nextGeneration = Number(nextTombstone.lifecycleGeneration || 0);
     const currentDeletedAt = Number(existing.deletedAt || 0);
-    const nextDeletedAt = Number(tombstone?.deletedAt || 0);
+    const nextDeletedAt = Number(nextTombstone.deletedAt || 0);
     if (nextGeneration > currentGeneration ||
       (nextGeneration === currentGeneration && nextDeletedAt >= currentDeletedAt)) {
-      merged[id] = tombstone;
+      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 || {}));
@@ -2164,45 +2207,92 @@ export const applyRecordTimeLabelSnapshot = (
   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 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: mergeLifecycleTombstoneDocuments(
-      currentDocs.lifecycleTombstones,
-      incomingDocs.lifecycleTombstones
+    lifecycleTombstones: buildV2LifecycleTombstoneDocuments(
+      remainingTombstones.deletedRecordTombstones,
+      remainingTombstones.deletedFolderTombstones
     )
   });
   const nextDocs = buildFirestoreV2DocumentsFromState(state);
@@ -5547,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,