@recordtimelabel/core 0.4.7 → 0.6.0

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.0`:
 
 ```json
-"@recordtimelabel/core": "0.4.6"
+"@recordtimelabel/core": "0.6.0"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -74,12 +74,21 @@ 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 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
 

package/package.json

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

@@ -0,0 +1,195 @@
+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 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) => toId(entry?.id)).filter(Boolean);
+
+    if (
+      hasConflict(changedRecords, deletedRecords) ||
+      hasConflict(changedFolders, deletedFolders) ||
+      hasConflict(changedTrash, deletedTrash) ||
+      hasConflict(lifecycleUpsertIds, lifecycleDeletes)
+    ) {
+      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 id = toId(entry?.id);
+      if (id) candidate.documents.lifecycleTombstones[id] = {...entry, id};
+    });
+    lifecycleDeletes.forEach((id) => {
+      delete candidate.documents.lifecycleTombstones[id];
+    });
+    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/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
+  };
+};