@recordtimelabel/core 0.4.6 → 0.4.7

package/README.md

@@ -131,8 +131,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.4.7",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",

package/src/index.js

@@ -31,12 +31,13 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.6';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.4.7';
 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 +3158,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 +3513,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 +3531,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 +3581,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 +4235,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) {