@recordtimelabel/core 0.4.6 → 0.5.0

package/README.md

@@ -75,11 +75,15 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `getActiveTrashEntries(entries, now)`
 - `RTL_TRASH_RETENTION_MS`
 
-The package exports four intentional entrypoints. The root (`@recordtimelabel/core`)
+The package exports five intentional entrypoints. The root (`@recordtimelabel/core`)
 keeps the complete backwards-compatible surface, `/protocol` contains only shared
 acknowledgement protocol helpers, `/firestore-v2` contains platform-neutral document
-and operation planners, and `/compat` contains the legacy `createSyncEngine` and
-`createRecordTimeLabelController` APIs.
+and operation planners, `/domain` contains group identity, Twitch VOD matching,
+legacy import, and channel-folder planning, and `/compat` contains the legacy
+`createSyncEngine` and `createRecordTimeLabelController` APIs.
+
+`RECORD_TIMELABEL_DOMAIN_CAPABILITIES` is a local release contract. It is not a
+gateway protocol capability.
 
 ### Durable sync engine
 
@@ -131,8 +135,16 @@ content is quarantined as an ID conflict. Rejected entries are terminal diagnost
 API; an intentional retry currently requires a new operation ID.
 
 The engine exposes `init()`, `dispatch(operations)`, `sync(reason)`,
-`syncUntilIdle(reason, options)`, `waitForIdle()`, `getSnapshot()`, `subscribe(listener)`,
-and `destroy()`. `sync()` preserves the one-FIFO-batch boundary. `syncUntilIdle()` drains
+`syncUntilIdle(reason, options)`, `waitForIdle()`, `waitForRemoteReady()`, `getSnapshot()`,
+`subscribe(listener)`, and `destroy()`. A cloud `subscribe(listener, context)` disposer may
+carry a `.ready` promise. After `init()` settles, hosts can await `waitForRemoteReady()` to
+prove that the current subscription's initial root observation and any bounded catch-up have
+settled; this wait rejects when the listener fails before readiness and fails closed across a
+session generation change or destroy. `init()` deliberately does not await this promise because
+the initial listener callback may itself enter the engine queue. Anonymous/no-subscription use
+is immediately ready.
+
+`sync()` preserves the one-FIFO-batch boundary. `syncUntilIdle()` drains
 subsequent batches up to `RTL_MAX_SYNC_DRAIN_ROUNDS`; it stops on retry/deferred/protocol
 conditions and reports `syncDrainLimitReached` as a retryable failure instead of silently
 reporting success. Hosts may provide `beforeRound({round, pendingCount, snapshot})` to block

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",
@@ -8,7 +8,8 @@
     ".": "./src/index.js",
     "./protocol": "./src/protocol.js",
     "./firestore-v2": "./src/firestore-v2.js",
-    "./compat": "./src/compat.js"
+    "./compat": "./src/compat.js",
+    "./domain": "./src/domain.js"
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs"

package/src/domain/channel-folder.js

@@ -0,0 +1,377 @@
+import {
+  SYSTEM_FOLDER_IDS,
+  normalizeId,
+  normalizeText,
+  toArray
+} from './shared.js';
+
+const FUZZY_MATCH_THRESHOLD = 0.88;
+const INVALID_CHANNEL_NAMES = new Set([
+  '',
+  'n/a',
+  'na',
+  'unknown',
+  'unknown channel',
+  'unknown streamer',
+  'fallback',
+  '未知頻道',
+  '未知频道'
+]);
+const RESERVED_TWITCH_PATHS = new Set([
+  'about', 'clips', 'directory', 'downloads', 'followers', 'following', 'jobs',
+  'p', 'profile', 'schedule', 'settings', 'store', 'subscriptions', 'videos'
+]);
+const CHANNEL_STOP_WORDS = new Set([
+  'ch', 'channel', 'channels', 'official', 'stream', 'streamer', 'streams',
+  'twitch', 'video', 'videos', 'vod', 'vods', 'youtube', 'yt'
+]);
+const EVIDENCE_SOURCE_RANK = {
+  folderName: 0,
+  folderAlias: 1,
+  folderAliasName: 1,
+  folderAliasHandle: 1,
+  folderAliasUrl: 1,
+  record: 2
+};
+
+const toText = (value) => (typeof value === 'string' ? value.trim() : '');
+
+export const normalizeChannelPlatform = (value) => {
+  const platform = toText(value).toLowerCase();
+  if (platform.includes('youtube') || platform === 'yt') return 'youtube';
+  if (platform.includes('twitch')) return 'twitch';
+  return platform || '';
+};
+
+export const isValidChannelName = (value) => {
+  const text = toText(value);
+  if (!text) return false;
+  const normalized = text.normalize('NFKC').toLowerCase();
+  if (INVALID_CHANNEL_NAMES.has(normalized)) return false;
+  return !/unknown|fallback/i.test(normalized);
+};
+
+const splitChannelTokens = (value, {removeStopWords = true} = {}) => {
+  const normalized = toText(value)
+    .normalize('NFKC')
+    .replace(/^@+/, '')
+    .replace(/['"`]/g, '')
+    .replace(/[()[\]{}]/g, ' ')
+    .toLowerCase();
+  return normalized
+    .split(/[^\p{L}\p{N}]+/u)
+    .map((token) => token.trim())
+    .filter((token) => token && (!removeStopWords || !CHANNEL_STOP_WORDS.has(token)));
+};
+
+export const getChannelMatchKey = (value) => splitChannelTokens(value).join('');
+
+export const getStrictChannelMatchKey = (value) => (
+  splitChannelTokens(value, {removeStopWords: false}).join('')
+);
+
+const getCandidateKey = (value) => {
+  const key = getChannelMatchKey(value);
+  if (key) return key;
+  return toText(value)
+    .normalize('NFKC')
+    .replace(/^@+/, '')
+    .replace(/[^\p{L}\p{N}]+/gu, '')
+    .toLowerCase();
+};
+
+const evidenceSourceRank = (source) => {
+  const text = String(source || '');
+  if (Object.hasOwn(EVIDENCE_SOURCE_RANK, text)) return EVIDENCE_SOURCE_RANK[text];
+  if (text.startsWith('record:')) return EVIDENCE_SOURCE_RANK.record;
+  return 3;
+};
+
+const addCandidate = (candidates, value, source) => {
+  if (!isValidChannelName(value)) return;
+  const text = toText(value);
+  const key = getCandidateKey(text);
+  if (!key) return;
+  const dedupeKey = `${source}:${key}`;
+  if (candidates.some((candidate) => candidate.dedupeKey === dedupeKey)) return;
+  candidates.push({
+    value: text,
+    key,
+    strictKey: getStrictChannelMatchKey(text),
+    source,
+    dedupeKey
+  });
+};
+
+const parseUrl = (value) => {
+  const text = toText(value);
+  if (!text) return null;
+  try {
+    return new URL(text);
+  } catch (_) {
+    try {
+      return new URL(`https://${text}`);
+    } catch (__) {
+      return null;
+    }
+  }
+};
+
+export const extractChannelHandleFromUrl = (value) => {
+  const url = parseUrl(value);
+  if (!url) return '';
+  const host = url.hostname.replace(/^www\./, '').toLowerCase();
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (parts.length === 0) return '';
+  if (host.endsWith('twitch.tv')) {
+    const first = parts[0].toLowerCase();
+    if (RESERVED_TWITCH_PATHS.has(first)) return '';
+    return parts[0];
+  }
+  if (host.endsWith('youtube.com')) {
+    if (parts[0]?.startsWith('@')) return parts[0];
+    if (['c', 'user'].includes(parts[0]) && parts[1]) return parts[1];
+    return '';
+  }
+  return '';
+};
+
+export const collectRecordTimeLabelChannelCandidates = (record = {}) => {
+  const candidates = [];
+  addCandidate(candidates, record.streamerName, 'streamerName');
+  addCandidate(candidates, record.channelName, 'channelName');
+  addCandidate(candidates, record.displayName, 'displayName');
+  addCandidate(candidates, record.channelHandle, 'channelHandle');
+  addCandidate(candidates, record.channelUsername, 'channelUsername');
+  addCandidate(candidates, record.username, 'username');
+  addCandidate(candidates, record.userName, 'userName');
+  [
+    record.channelUrl,
+    record.channelBaseUrl,
+    record.videoUrl,
+    record.originalVideoUrl,
+    record.jumpUrl
+  ].forEach((url) => {
+    addCandidate(candidates, extractChannelHandleFromUrl(url), 'urlHandle');
+  });
+  return candidates.map(({dedupeKey: _dedupeKey, ...candidate}) => candidate);
+};
+
+const collectFolderChannelCandidates = (folder = {}, folderRecords = []) => {
+  const candidates = [];
+  addCandidate(candidates, folder.name, 'folderName');
+  if (Array.isArray(folder.aliases)) {
+    folder.aliases.forEach((alias) => {
+      if (typeof alias === 'string') addCandidate(candidates, alias, 'folderAlias');
+      else if (alias && typeof alias === 'object') {
+        addCandidate(candidates, alias.name, 'folderAliasName');
+        addCandidate(candidates, alias.handle, 'folderAliasHandle');
+        addCandidate(candidates, alias.url, 'folderAliasUrl');
+      }
+    });
+  }
+  folderRecords.forEach((record) => {
+    collectRecordTimeLabelChannelCandidates(record).forEach((candidate) => {
+      addCandidate(candidates, candidate.value, `record:${candidate.source}`);
+    });
+  });
+  return candidates;
+};
+
+const collectFolderPlatforms = (folderRecords = []) => {
+  const platforms = new Set();
+  folderRecords.forEach((record) => {
+    const platform = normalizeChannelPlatform(record?.platform);
+    if (platform) platforms.add(platform);
+  });
+  return platforms;
+};
+
+const jaroWinkler = (first, second) => {
+  if (first === second) return 1;
+  if (!first || !second) return 0;
+  const firstLength = first.length;
+  const secondLength = second.length;
+  const matchDistance = Math.floor(Math.max(firstLength, secondLength) / 2) - 1;
+  const firstMatches = new Array(firstLength).fill(false);
+  const secondMatches = new Array(secondLength).fill(false);
+  let matches = 0;
+  for (let i = 0; i < firstLength; i += 1) {
+    const start = Math.max(0, i - matchDistance);
+    const end = Math.min(i + matchDistance + 1, secondLength);
+    for (let j = start; j < end; j += 1) {
+      if (secondMatches[j] || first[i] !== second[j]) continue;
+      firstMatches[i] = true;
+      secondMatches[j] = true;
+      matches += 1;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  let transpositions = 0;
+  let secondIndex = 0;
+  for (let i = 0; i < firstLength; i += 1) {
+    if (!firstMatches[i]) continue;
+    while (!secondMatches[secondIndex]) secondIndex += 1;
+    if (first[i] !== second[secondIndex]) transpositions += 1;
+    secondIndex += 1;
+  }
+  const jaro = (
+    (matches / firstLength) +
+    (matches / secondLength) +
+    ((matches - (transpositions / 2)) / matches)
+  ) / 3;
+  let prefix = 0;
+  const maxPrefix = Math.min(4, firstLength, secondLength);
+  while (prefix < maxPrefix && first[prefix] === second[prefix]) prefix += 1;
+  return jaro + (prefix * 0.1 * (1 - jaro));
+};
+
+const compareCandidates = (incoming, target) => {
+  if (!incoming?.key || !target?.key) return {score: 0, reason: 'empty'};
+  if (incoming.strictKey && incoming.strictKey === target.strictKey) {
+    return {score: 1, reason: 'exact-key'};
+  }
+  if (incoming.key === target.key) return {score: 0.94, reason: 'normalized-key'};
+  const shorter = incoming.key.length <= target.key.length ? incoming.key : target.key;
+  const longer = incoming.key.length > target.key.length ? incoming.key : target.key;
+  if (shorter.length >= 6 && longer.includes(shorter) && (shorter.length / longer.length) >= 0.65) {
+    return {score: 0.93, reason: 'contained-key'};
+  }
+  return {score: jaroWinkler(incoming.key, target.key), reason: 'jaro-winkler'};
+};
+
+const folderAllowsFuzzyMatch = (incomingPlatform, folderPlatforms) => {
+  if (!incomingPlatform || folderPlatforms.size === 0) return false;
+  return [...folderPlatforms].some((platform) => platform !== incomingPlatform);
+};
+
+const isBetterMatch = (candidate, current, folderOrderIndex) => {
+  if (!current) return true;
+  if (candidate.score !== current.score) return candidate.score > current.score;
+  const candidateEvidence = evidenceSourceRank(candidate.evidenceSource);
+  const currentEvidence = evidenceSourceRank(current.evidenceSource);
+  if (candidateEvidence !== currentEvidence) return candidateEvidence < currentEvidence;
+  const candidateOrder = folderOrderIndex.get(candidate.folderId) ?? Number.POSITIVE_INFINITY;
+  const currentOrder = folderOrderIndex.get(current.folderId) ?? Number.POSITIVE_INFINITY;
+  if (candidateOrder !== currentOrder) return candidateOrder < currentOrder;
+  return String(candidate.folderId).localeCompare(String(current.folderId)) < 0;
+};
+
+export const findBestRecordTimeLabelChannelFolder = ({
+  record,
+  folders = [],
+  recordsByFolder = {},
+  folderOrder = [],
+  excludedFolderIds = SYSTEM_FOLDER_IDS,
+  fuzzyThreshold = FUZZY_MATCH_THRESHOLD
+} = {}) => {
+  const incomingCandidates = collectRecordTimeLabelChannelCandidates(record);
+  if (incomingCandidates.length === 0) return null;
+
+  const incomingPlatform = normalizeChannelPlatform(record?.platform);
+  const excludedIds = excludedFolderIds instanceof Set
+    ? excludedFolderIds
+    : new Set(excludedFolderIds || []);
+  const folderOrderIndex = new Map(
+    (Array.isArray(folderOrder) ? folderOrder : []).map((folderId, index) => [folderId, index])
+  );
+  (folders || []).forEach((folder, index) => {
+    if (folder?.id && !folderOrderIndex.has(folder.id)) folderOrderIndex.set(folder.id, 100000 + index);
+  });
+
+  let bestMatch = null;
+  (folders || []).forEach((folder) => {
+    if (!folder?.id || excludedIds.has(folder.id) || SYSTEM_FOLDER_IDS.has(folder.id)) return;
+    const folderRecords = Array.isArray(recordsByFolder?.[folder.id]) ? recordsByFolder[folder.id] : [];
+    const folderPlatforms = collectFolderPlatforms(folderRecords);
+    const allowFuzzy = folderAllowsFuzzyMatch(incomingPlatform, folderPlatforms);
+    const targetCandidates = collectFolderChannelCandidates(folder, folderRecords);
+
+    incomingCandidates.forEach((incomingCandidate) => {
+      targetCandidates.forEach((targetCandidate) => {
+        const comparison = compareCandidates(incomingCandidate, targetCandidate);
+        const isExact = comparison.score === 1;
+        const isAcceptedFuzzy = allowFuzzy && comparison.score >= fuzzyThreshold;
+        if (!isExact && !isAcceptedFuzzy) return;
+        const match = {
+          folderId: folder.id,
+          folder: {id: folder.id, name: folder.name || ''},
+          score: comparison.score,
+          reason: comparison.reason,
+          evidenceSource: targetCandidate.source,
+          incomingCandidate,
+          targetCandidate: {
+            value: targetCandidate.value,
+            key: targetCandidate.key,
+            strictKey: targetCandidate.strictKey,
+            source: targetCandidate.source
+          },
+          crossPlatform: allowFuzzy,
+          folderPlatforms: [...folderPlatforms]
+        };
+        if (isBetterMatch(match, bestMatch, folderOrderIndex)) bestMatch = match;
+      });
+    });
+  });
+
+  return bestMatch;
+};
+
+export const isPendingChannelFolderId = (folderId) => (
+  typeof folderId === 'string' && folderId.startsWith('pending-channel-folder-')
+);
+
+export const buildRecordTimeLabelChannelFolderPlan = ({
+  channelGroups = {},
+  folders = [],
+  recordsByFolder = {},
+  folderOrder = []
+} = {}) => {
+  const foldersToCreate = [];
+  const channelFolderAssignments = {};
+  const plannedFolders = [...(Array.isArray(folders) ? folders : [])];
+  const plannedRecords = {...recordsByFolder};
+
+  Object.entries(channelGroups || {}).forEach(([channelName, entries = []]) => {
+    const representativeRecord = {
+      ...(entries[0]?.record || {}),
+      streamerName: channelName
+    };
+    const sourceFolderIds = new Set(entries.map((entry) => entry.currentFolderId).filter(Boolean));
+    const exactNameFolder = plannedFolders.find((folder) => (
+      folder?.id &&
+      !SYSTEM_FOLDER_IDS.has(folder.id) &&
+      normalizeText(folder.name).toLowerCase() === normalizeText(channelName).toLowerCase()
+    ));
+    const matchedFolder = exactNameFolder || findBestRecordTimeLabelChannelFolder({
+      record: representativeRecord,
+      folders: plannedFolders.filter((folder) => !sourceFolderIds.has(folder?.id)),
+      recordsByFolder: plannedRecords,
+      folderOrder
+    })?.folder;
+
+    if (matchedFolder) {
+      channelFolderAssignments[channelName] = isPendingChannelFolderId(matchedFolder.id)
+        ? {tempId: matchedFolder.id}
+        : {folderId: matchedFolder.id};
+      plannedRecords[matchedFolder.id] = [
+        ...(plannedRecords[matchedFolder.id] || []),
+        ...entries.map((entry) => entry.record)
+      ];
+      return;
+    }
+
+    const tempId = `pending-channel-folder-${foldersToCreate.length}`;
+    foldersToCreate.push({channelName, tempId});
+    channelFolderAssignments[channelName] = {tempId};
+    plannedFolders.push({id: tempId, name: channelName});
+    plannedRecords[tempId] = entries.map((entry) => entry.record);
+  });
+
+  return {
+    foldersToCreate,
+    channelFolderAssignments,
+    plannedRecords
+  };
+};