@recordtimelabel/core 0.4.5 → 0.4.7

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.4` (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 strict durable transport contract is prepared in package version `0.4.6` (publish it before updating consumers):
 
 ```json
-"@recordtimelabel/core": "0.4.4"
+"@recordtimelabel/core": "0.4.6"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -33,6 +33,8 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `applyOperation(state, operation)`
 - `applyRecordTimeLabelOperation(state, operation)`
 - `createRecordTimeLabelSyncEngine({ storage, cloud, session, client, clock, logger })`
+- `RTL_MAX_SYNC_DRAIN_ROUNDS`
+- `RTL_SYNC_DRAIN_RETRY_DELAY_MS`
 - `RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES`
 - `RECORD_TIMELABEL_PROTOCOL_CAPABILITIES`
 - `toRecordTimeLabelWireOperation(operation)`
@@ -121,13 +123,32 @@ modes with a unique `attemptId`; all require a fresh logical attempt. Structured
 failures, missing state, and missing/invalid revisions fail closed. UID or workspace
 epoch changes clear the visible workspace and require `init()` before another dispatch
 or sync; token refresh for the same UID/epoch only refreshes the subscription fence. An
-operation acknowledgement records its revision diagnostically but advances
-`remoteBaseline.revision` only with a complete state; revision gaps trigger a fresh bootstrap.
-
-The engine exposes `init()`, `dispatch(operations)`, `sync(reason)`, `getSnapshot()`,
-`subscribe(listener)`, and `destroy()`. `getSnapshot().state` is derived by replaying pending
-operations over `remoteBaseline.state`; rejected operations are kept in diagnostics and are not
-replayed. Session tokens are used for fencing but are never persisted. The legacy
+operation acknowledgement records its revision diagnostically and advances
+`remoteBaseline.revision` with a complete state, or with an all-applied no-state ACK at
+exactly the next revision; larger revision gaps trigger a fresh bootstrap. Re-dispatching
+the same operation ID and wire content is reported as deduplicated, while different wire
+content is quarantined as an ID conflict. Rejected entries are terminal diagnostics in this
+API; an intentional retry currently requires a new operation ID.
+
+The engine exposes `init()`, `dispatch(operations)`, `sync(reason)`,
+`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
+gateway writes while a host-specific hydration/import gate is active, and `runRound({round,
+pendingCount, run})` to serialize that gate check and the gateway call with host mutations.
+`getSnapshot().state` is derived by replaying pending operations over `remoteBaseline.state`;
+rejected operations are kept in diagnostics and are not replayed. Session tokens are used for
+fencing but are never persisted. The legacy
 `createSyncEngine` and app adapters remain available and are not implicitly migrated by this API.
 
 `expandedGroups` is a local view projection, not durable cloud domain state. Durable workspaces,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.4.5",
+  "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,17 +31,20 @@ const REQUIRED_FOLDERS = [
   { id: DEFAULT_FOLDER_ID, name: 'Uncategorized' }
 ];
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.4.5';
+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
 ]);
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
+export const RTL_MAX_SYNC_DRAIN_ROUNDS = 50;
+export const RTL_SYNC_DRAIN_RETRY_DELAY_MS = 1000;
 export const RTL_MAX_REQUEST_BYTES = 256 * 1024;
 export const RTL_MAX_TARGET_WRITES = 100;
 export const RTL_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
@@ -2954,6 +2957,7 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
     });
   }
   let rejectedCount = 0;
+  let deduplicatedCount = 0;
   toArray(operations).forEach((operation, index) => {
     const id = normalizeId(operation?.id);
     const fingerprint = rtlOperationWireFingerprint(operation);
@@ -2961,7 +2965,10 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
     let reason = rtlOperationIdentityReason(operation, workspace);
     if (!reason) reason = rtlLifecycleOperationReason(operation, lifecycleState);
     if (!reason && knownFingerprint) {
-      if (knownFingerprint === fingerprint) return;
+      if (knownFingerprint === fingerprint) {
+        deduplicatedCount += 1;
+        return;
+      }
       reason = RECORD_TIMELABEL_OPERATION_IDENTITY_REASONS.ID_CONFLICT;
     }
     if (!reason) {
@@ -2991,7 +2998,7 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
       }
     };
   });
-  return {accepted, rejected, rejectedCount};
+  return {accepted, rejected, rejectedCount, deduplicatedCount};
 };
 
 const rtlExtractSession = (session, fallbackEpoch = 0) => {
@@ -3151,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();
@@ -3287,7 +3305,9 @@ export const createRecordTimeLabelSyncEngine = ({
   // normalizeBootstrapResponse accepts) or `{success: false,
   // bootstrapRequired: true}`; it may throw on transport errors.  Gap
   // recovery prefers it over `cloud.bootstrap` and falls back to a fresh
-  // bootstrap walk whenever it fails or is unavailable.
+  // bootstrap walk on transport/protocol failure. A successful but stale
+  // catch-up response is fail-closed: falling back would hide a revision
+  // contract violation and could apply a baseline older than the ACK.
   const recoverBaseline = async (context, targetRevision, mode) => {
     if (typeof cloud?.catchUp === 'function') {
       try {
@@ -3300,6 +3320,9 @@ export const createRecordTimeLabelSyncEngine = ({
           return requireBootstrapRevision(normalizeBootstrapResponse(caught), targetRevision);
         }
       } catch (error) {
+        if (error?.code === 'recordtimelabel_bootstrap_revision_behind_required') {
+          throw error;
+        }
         logger?.warn?.('[RecordTimeLabelCore] catch-up failed, falling back to bootstrap', error);
       }
     }
@@ -3490,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};
       }
@@ -3506,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);
@@ -3514,32 +3581,104 @@ 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 () => {
     const captured = capture();
     const loaded = await storage.load();
     if (!(await isCurrent(captured))) return getSnapshot();
-    // The reuse predicate must read the RAW loaded owner before
-    // normalizeLoadedWorkspace adopts the current session identity onto the
-    // workspace; epochs are intentionally not compared (consumers may advance
-    // the persisted epoch on every launch).
+    // Read the raw owner and baseline before normalizeLoadedWorkspace adopts
+    // the current session identity. Reuse still validates the normalized
+    // candidate below because owner/epoch fences may replace loaded data with
+    // an empty workspace.
     const loadedOwnerUid = rtlNormalizeUid(loaded?.ownerUid);
-    const committedRevision = Number(loaded?.remoteBaseline?.revision || 0);
+    const loadedBaseline = loaded?.remoteBaseline;
+    const committedRevision = Number(loadedBaseline?.revision);
+    const hasValidCommittedBaseline = rtlDurableIsObject(loadedBaseline) &&
+      rtlDurableIsObject(loadedBaseline.state) &&
+      Number.isFinite(committedRevision) &&
+      committedRevision > 0;
     let candidate = normalizeLoadedWorkspace(loaded, captured);
     const identityChecked = rtlQuarantineOperations(
       candidate,
@@ -3552,7 +3691,10 @@ export const createRecordTimeLabelSyncEngine = ({
 
     const canReuseCommitted = initialBaseline === 'reuse-committed' &&
       captured?.uid && loadedOwnerUid === rtlNormalizeUid(captured.uid) &&
-      committedRevision > 0;
+      hasValidCommittedBaseline &&
+      candidate.ownerUid === rtlNormalizeUid(captured.uid) &&
+      candidate.remoteBaseline.revision === committedRevision &&
+      (!captured.hasEpoch || Number(candidate.workspaceEpoch) === Number(captured.workspaceEpoch));
     if (captured?.uid && typeof cloud?.bootstrap === 'function' && !canReuseCommitted) {
       let bootstrap;
       try {
@@ -3671,10 +3813,20 @@ export const createRecordTimeLabelSyncEngine = ({
         type: 'local_applied',
         operations: clone([...durableOperations, ...viewOperations]),
         operation: clone(viewOperations.at(-1) || durableOperations.at(-1)),
-        rejectedCount: identityChecked.rejectedCount
+        rejectedCount: identityChecked.rejectedCount,
+        deduplicatedCount: identityChecked.deduplicatedCount
+      });
+    } else if (identityChecked.deduplicatedCount > 0 && identityChecked.rejectedCount === 0) {
+      notify({
+        type: 'operations_deduplicated',
+        deduplicatedCount: identityChecked.deduplicatedCount
       });
     } else {
-      notify({type: 'operations_rejected', rejectedCount: identityChecked.rejectedCount});
+      notify({
+        type: 'operations_rejected',
+        rejectedCount: identityChecked.rejectedCount,
+        deduplicatedCount: identityChecked.deduplicatedCount
+      });
     }
     return getSnapshot();
   };
@@ -3868,6 +4020,21 @@ export const createRecordTimeLabelSyncEngine = ({
     const responseState = responseBaseline?.state ?? responseBaseline?.data;
     if (rtlDurableIsObject(responseState)) {
       applyRemoteBaseline(candidate, responseBaseline);
+    } else if (
+      rejectedCount === 0 &&
+      !sawRetryable &&
+      appliedOperations.length === completedOperations.length &&
+      appliedOperations.length > 0 &&
+      Number.isFinite(responseRevision) &&
+      responseRevision === candidate.remoteBaseline.revision + 1
+    ) {
+      // The v2 gateway ACK is intentionally compact and omits state. Promote
+      // only an all-applied transaction at exactly the next revision; any
+      // larger jump still needs an authoritative bootstrap baseline.
+      candidate.remoteBaseline.revision = responseRevision;
+      if (Object.prototype.hasOwnProperty.call(responseBaseline || {}, 'changeCursor')) {
+        candidate.remoteBaseline.changeCursor = responseBaseline.changeCursor ?? null;
+      }
     } else if (
       rejectedCount === 0 &&
       Number.isFinite(responseRevision) &&
@@ -3930,6 +4097,120 @@ export const createRecordTimeLabelSyncEngine = ({
     };
   };
 
+  // `sync()` intentionally sends only one immutable FIFO batch. Consumers
+  // that own the outbox scan may use this method to drain subsequent batches
+  // without reimplementing the stop conditions in each host application.
+  // `beforeRound` is a host gate (hydration/import/account state); `runRound`
+  // can serialize that gate check and the gateway call with host mutations.
+  const syncUntilIdleInternal = async (reason, options = {}) => {
+    const maxRounds = Number.isSafeInteger(Number(options?.maxRounds)) &&
+      Number(options.maxRounds) > 0
+      ? Number(options.maxRounds)
+      : RTL_MAX_SYNC_DRAIN_ROUNDS;
+    const beforeRound = typeof options?.beforeRound === 'function'
+      ? options.beforeRound
+      : null;
+    const runRound = typeof options?.runRound === 'function'
+      ? options.runRound
+      : null;
+    const totals = {
+      appliedCount: 0,
+      syncedCount: 0,
+      rejectedCount: 0,
+      retryCount: 0,
+      identityRejectedCount: 0
+    };
+    let lastResult = null;
+    let rounds = 0;
+
+    for (let round = 0; round < maxRounds; round += 1) {
+      rounds += 1;
+      const executeRound = async () => {
+        if (beforeRound) {
+          const gate = await beforeRound({
+            round,
+            pendingCount: workspace.pendingOperations.length,
+            snapshot: getSnapshot()
+          });
+          if (gate === false || gate?.allowed === false) {
+            const details = gate && typeof gate === 'object' ? {...gate} : {};
+            delete details.allowed;
+            return {
+              ...details,
+              success: true,
+              deferred: true,
+              pendingSync: workspace.pendingOperations.length > 0,
+              reason: details.reason || 'sync_gate_blocked',
+              pendingCount: workspace.pendingOperations.length
+            };
+          }
+        }
+        return syncInternal(reason);
+      };
+      const result = runRound
+        ? await runRound({
+            round,
+            pendingCount: workspace.pendingOperations.length,
+            run: executeRound
+          })
+        : await executeRound();
+      lastResult = result && typeof result === 'object'
+        ? result
+        : {success: false, reason: 'sync_round_missing_result'};
+      Object.keys(totals).forEach((key) => {
+        const value = Number(lastResult?.[key]);
+        if (Number.isFinite(value)) totals[key] += value;
+      });
+
+      const pendingCount = Number(lastResult?.pendingCount ?? workspace.pendingOperations.length);
+      const madeProgress = Number(lastResult?.syncedCount || lastResult?.appliedCount || 0) > 0 ||
+        Number(lastResult?.rejectedCount || 0) > 0 ||
+        Number(lastResult?.retryCount || 0) > 0 ||
+        Number(lastResult?.identityRejectedCount || 0) > 0;
+      if (
+        lastResult.deferred ||
+        lastResult.success === false ||
+        lastResult.retryable ||
+        lastResult.protocolError ||
+        lastResult.skipped ||
+        lastResult.retryCount > 0 ||
+        pendingCount === 0 ||
+        !madeProgress
+      ) break;
+    }
+
+    const pendingCount = Number(lastResult?.pendingCount ?? workspace.pendingOperations.length);
+    const result = {
+      ...(lastResult || {success: true}),
+      ...totals,
+      pendingCount,
+      syncDrainRounds: rounds,
+      drained: pendingCount === 0
+    };
+    if (
+      pendingCount > 0 &&
+      rounds >= maxRounds &&
+      !result.deferred &&
+      result.success !== false &&
+      !result.retryable &&
+      !result.skipped
+    ) {
+      const retryAt = now() + RTL_SYNC_DRAIN_RETRY_DELAY_MS;
+      return {
+        ...result,
+        success: false,
+        retryable: true,
+        pendingSync: true,
+        reason: 'sync_drain_limit_reached',
+        syncDrainLimitReached: true,
+        drainLimitReached: true,
+        retryAfterMs: RTL_SYNC_DRAIN_RETRY_DELAY_MS,
+        retryAt
+      };
+    }
+    return result;
+  };
+
   const engine = {
     init() {
       return enqueue(async () => {
@@ -3946,6 +4227,26 @@ export const createRecordTimeLabelSyncEngine = ({
       return enqueue(() => syncInternal(reason));
     },
 
+    syncUntilIdle(reason, options = {}) {
+      return enqueue(() => syncUntilIdleInternal(reason, options));
+    },
+
+    waitForIdle() {
+      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) {
@@ -4996,6 +5297,8 @@ export default {
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   RTL_SYNC_PROTOCOL_VERSION,
   RTL_MAX_OPERATIONS_PER_REQUEST,
+  RTL_MAX_SYNC_DRAIN_ROUNDS,
+  RTL_SYNC_DRAIN_RETRY_DELAY_MS,
   RTL_MAX_REQUEST_BYTES,
   RTL_MAX_TARGET_WRITES,
   RTL_TRASH_RETENTION_MS,