@recordtimelabel/core 0.4.6 → 0.5.0

package/src/domain/twitch-vod.js

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

package/src/domain.js

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

package/src/index.js

@@ -31,12 +31,69 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.6';
+import {
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildKnownTwitchVodRecordPatches,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelChannelFolderPlan,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  canonicalizeRecordTimeLabelGroupView,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
+  normalizeLegacyRecordTimeLabelImport,
+  normalizeVodTitleForMatch,
+  remapLegacyRecordTimeLabelFolderAliases,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+} from './domain.js';
+
+export {
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
+  buildKnownTwitchVodRecordPatches,
+  buildLegacyRecordTimeLabelGroupId,
+  buildRecordTimeLabelChannelFolderPlan,
+  buildRecordTimeLabelGroupIndex,
+  buildRecordTimeLabelGroupMetadata,
+  buildRecordTimeLabelGroupReorderOperationId,
+  buildRecordTimeLabelStandaloneGroupId,
+  buildRecordTimeLabelVodPatchOperationId,
+  calculateVodTitleSimilarity,
+  canonicalizeRecordTimeLabelGroupView,
+  collectRecordTimeLabelChannelCandidates,
+  extractChannelHandleFromUrl,
+  extractTwitchVodIdFromUrl,
+  extractYouTubeVideoIdFromUrl,
+  findBestRecordTimeLabelChannelFolder,
+  getChannelMatchKey,
+  isPendingChannelFolderId,
+  isValidChannelName,
+  normalizeLegacyRecordTimeLabelImport,
+  normalizeVodTitleForMatch,
+  remapLegacyRecordTimeLabelFolderAliases,
+  scoreTwitchVodCandidate,
+  selectBestMatchingTwitchVod
+};
+
+export const RECORD_TIMELABEL_CORE_VERSION = '0.5.0';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
   'baseline-refresh-after-rejection',
   'sync-batch-boundary',
+  'remote-subscription-readiness',
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
@@ -3157,6 +3214,17 @@ export const createRecordTimeLabelSyncEngine = ({
   let unsubscribeCloud = null;
   let unsubscribeSession = null;
   let subscriptionContext = null;
+  let remoteReadyGeneration = 0;
+  let remoteReadyState = {
+    generation: 0,
+    settled: true,
+    promise: Promise.resolve({
+      success: true,
+      skipped: true,
+      reason: 'not_initialized',
+      generation: 0
+    })
+  };
   let bootstrapAttemptSequence = 0;
   const listeners = new Set();
   let queue = Promise.resolve();
@@ -3501,7 +3569,9 @@ export const createRecordTimeLabelSyncEngine = ({
       return {success: true, ignored: true};
     }
     let baselineValue = remoteValue;
-    if (remoteRevision > candidate.remoteBaseline.revision + 1) {
+    const remoteState = remote?.state ?? remote?.data;
+    const revisionOnlyNotification = !rtlDurableIsObject(remoteState);
+    if (remoteRevision > candidate.remoteBaseline.revision + 1 || revisionOnlyNotification) {
       if (typeof cloud?.bootstrap !== 'function') {
         return {success: false, reason: 'revision_gap', bootstrapRequired: true};
       }
@@ -3517,7 +3587,49 @@ export const createRecordTimeLabelSyncEngine = ({
     return getSnapshot();
   };
 
-  const stopCloudSubscription = () => {
+  const createRemoteReadyState = () => {
+    const generation = ++remoteReadyGeneration;
+    let resolvePromise;
+    let rejectPromise;
+    const state = {
+      generation,
+      settled: false,
+      promise: new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+      }),
+      resolve(value = {}) {
+        if (state.settled) return;
+        state.settled = true;
+        resolvePromise({
+          success: true,
+          ...(value && typeof value === 'object' ? value : {}),
+          generation
+        });
+      },
+      reject(error) {
+        if (state.settled) return;
+        state.settled = true;
+        rejectPromise(error);
+      }
+    };
+    // Readiness is an opt-in host boundary. Keep a rejection observable to a
+    // waiter without turning clients that have not adopted it yet into an
+    // unhandled-rejection source.
+    state.promise.catch(() => null);
+    return state;
+  };
+
+  const staleRemoteReady = (state, reason = 'stale_session') => {
+    if (!state || state.settled) return;
+    state.resolve({success: false, stale: true, reason});
+  };
+
+  const isCurrentRemoteReady = (state) => (
+    !destroyed && remoteReadyState === state && remoteReadyState.generation === state.generation
+  );
+
+  const stopCloudSubscription = ({settleReady = true} = {}) => {
     if (typeof unsubscribeCloud === 'function') {
       try { unsubscribeCloud(); } catch (error) {
         logger?.error?.('[RecordTimeLabelCore] durable unsubscribe failed', error);
@@ -3525,20 +3637,87 @@ export const createRecordTimeLabelSyncEngine = ({
     }
     unsubscribeCloud = null;
     subscriptionContext = null;
+    if (settleReady) staleRemoteReady(remoteReadyState);
   };
 
   const startCloudSubscription = (captured, candidate) => {
     stopCloudSubscription();
-    if (typeof cloud?.subscribe !== 'function' || !initialized || hydrationRequired) return;
+    const readyState = createRemoteReadyState();
+    remoteReadyState = readyState;
+    if (!initialized || hydrationRequired) {
+      readyState.resolve({success: false, skipped: true, reason: 'hydration_required'});
+      return;
+    }
+    if (!captured?.uid) {
+      readyState.resolve({skipped: true, reason: 'anonymous'});
+      return;
+    }
+    if (typeof cloud?.subscribe !== 'function') {
+      readyState.resolve({skipped: true, reason: 'no_subscription'});
+      return;
+    }
     const context = rtlSessionContext(captured, candidate, client);
     subscriptionContext = context;
-    unsubscribeCloud = cloud.subscribe((remoteValue) => {
-      if (destroyed) return;
-      return enqueue(() => processRemote(remoteValue, captured)).catch((error) => {
+    let subscriptionReturned = false;
+    let adapterReadyExpected = false;
+    let firstCallbackResult = null;
+    const onRemote = (remoteValue) => {
+      if (destroyed || !isCurrentRemoteReady(readyState)) {
+        return Promise.resolve({success: false, stale: true, reason: 'stale_session'});
+      }
+      const callbackResult = enqueue(() => processRemote(remoteValue, captured));
+      if (!firstCallbackResult) firstCallbackResult = callbackResult;
+      callbackResult.then((result) => {
+        if (
+          subscriptionReturned &&
+          !adapterReadyExpected &&
+          isCurrentRemoteReady(readyState)
+        ) {
+          readyState.resolve({
+            revision: workspace.remoteBaseline.revision,
+            result
+          });
+        }
+      }).catch((error) => {
+        if (isCurrentRemoteReady(readyState) && !readyState.settled) {
+          readyState.reject(error);
+        }
         logger?.error?.('[RecordTimeLabelCore] durable remote callback failed', error);
-        return {success: false, error};
       });
-    }, context);
+      return callbackResult;
+    };
+    let disposer;
+    try {
+      disposer = cloud.subscribe(onRemote, context);
+    } catch (error) {
+      readyState.reject(error);
+      logger?.error?.('[RecordTimeLabelCore] durable subscribe failed', error);
+      return;
+    }
+    unsubscribeCloud = typeof disposer === 'function' ? disposer : null;
+    adapterReadyExpected = Boolean(disposer?.ready && typeof disposer.ready.then === 'function');
+    subscriptionReturned = true;
+    if (adapterReadyExpected) {
+      Promise.resolve(disposer.ready).then((result) => {
+        if (!isCurrentRemoteReady(readyState)) return;
+        readyState.resolve({
+          revision: workspace.remoteBaseline.revision,
+          result
+        });
+      }).catch((error) => {
+        if (isCurrentRemoteReady(readyState) && !readyState.settled) {
+          readyState.reject(error);
+        }
+      });
+    } else if (firstCallbackResult) {
+      firstCallbackResult.then((result) => {
+        if (!isCurrentRemoteReady(readyState)) return;
+        readyState.resolve({
+          revision: workspace.remoteBaseline.revision,
+          result
+        });
+      }).catch(() => null);
+    }
   };
 
   const initialize = async () => {
@@ -4112,6 +4291,18 @@ export const createRecordTimeLabelSyncEngine = ({
       return queue.catch(() => null);
     },
 
+    waitForRemoteReady() {
+      if (destroyed) {
+        return Promise.resolve({
+          success: false,
+          stale: true,
+          reason: 'stale_session',
+          generation: remoteReadyState.generation
+        });
+      }
+      return remoteReadyState.promise;
+    },
+
     getSnapshot,
 
     subscribe(listener) {
@@ -5154,6 +5345,8 @@ export const buildOperationsFromSnapshotDiff = ({
 
 export default {
   RECORD_TIMELABEL_CORE_VERSION,
+  RECORD_GROUP_IDENTITY_VERSION,
+  RECORD_TIMELABEL_DOMAIN_CAPABILITIES,
   RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,