@recordtimelabel/core 0.6.4 → 0.6.6

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 release target is `0.6.4`; verify that its registry tarball and lockfile integrity are available 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 release target is `0.6.6`; verify that its registry tarball and lockfile integrity are available before updating consumers:
 
 ```json
-"@recordtimelabel/core": "0.6.4"
+"@recordtimelabel/core": "0.6.6"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -134,10 +134,22 @@ The persisted workspace is versioned and contains only durable data:
   remoteBaseline: { state, revision: 12, changeCursor: 'cursor-12' },
   pendingOperations: [],
   rejectedOperations: {},
-  syncMeta: {}
+  syncMeta: {
+    // Core-owned resume fence; the cursor itself remains opaque adapter data.
+    changeCursorBinding: {
+      ownerUid: 'user-id', uid: 'user-id', workspaceEpoch: 3,
+      authSessionBinding: 'auth-session-3'
+    }
+  }
 }
 ```
 
+`remoteBaseline.changeCursor` is an opaque string owned by the cloud adapter and
+must remain byte-for-byte stable across persistence. Core stores the owner,
+workspace-epoch, and non-credential auth binding separately in
+`syncMeta.changeCursorBinding` so a committed workspace can be resumed without
+embedding session credentials in the cursor.
+
 Every normalized pending operation also carries `ownerUid` and a non-negative
 `workspaceEpoch`. Dispatch stamps these fields from the captured session; legacy
 operations missing them inherit the migrated workspace identity. An operation whose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recordtimelabel/core",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "type": "module",
   "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
   "main": "./src/index.js",

package/src/index.js

@@ -141,7 +141,7 @@ export {
   selectBestMatchingTwitchVod
 };
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.6.4';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.6.6';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -1041,9 +1041,9 @@ export const applyOperation = (state = {}, operation = {}) => {
 
     case OPERATION_TYPES.RECORD_MOVE: {
       const recordId = normalizeId(payload.recordId || payload.id || payload.record?.id);
-      const rawTargetFolderId = normalizeId(payload.targetFolderId || payload.folderId);
+      const rawTargetFolderId = rtlFirstPresent(payload, ['targetFolderId', 'folderId']);
       if (!recordId || !rtlIsSafeDocumentId(recordId) ||
-        (rawTargetFolderId && !rtlIsSafeDocumentId(rawTargetFolderId))) return normalized;
+        !rtlIsSafeDocumentId(rawTargetFolderId)) return normalized;
       const targetFolderId = safeFolderId(rawTargetFolderId);
       const entry = findRecordEntry(nextState.records, recordId);
       if (!entry) return normalized;
@@ -1145,6 +1145,10 @@ export const applyOperation = (state = {}, operation = {}) => {
           originalRecordIndex: Number.isInteger(payload.originalRecordIndex)
             ? payload.originalRecordIndex
             : Math.max(0, Number(existingEntry?.index || 0)),
+          originalGroupId: String(payload.originalGroupId || '').trim(),
+          originalGroupOrderIndex: Number.isInteger(payload.originalGroupOrderIndex)
+            ? payload.originalGroupOrderIndex
+            : -1,
           lifecycleGeneration,
           deletedAt,
           purgeAt: toFiniteTimestamp(payload.purgeAt) || deletedAt + RTL_TRASH_RETENTION_MS,
@@ -1206,6 +1210,16 @@ export const applyOperation = (state = {}, operation = {}) => {
       );
       targetRecords.splice(restoreIndex, 0, restoredRecord);
       nextState.records[targetFolderId] = targetRecords;
+      const originalGroupId = String(trashEntry.originalGroupId || '').trim();
+      const originalGroupOrderIndex = Number.isInteger(trashEntry.originalGroupOrderIndex)
+        ? trashEntry.originalGroupOrderIndex
+        : -1;
+      if (originalGroupId && originalGroupOrderIndex >= 0 &&
+        !nextState.groupOrder.includes(originalGroupId)) {
+        const groupOrder = [...nextState.groupOrder];
+        groupOrder.splice(Math.min(originalGroupOrderIndex, groupOrder.length), 0, originalGroupId);
+        nextState.groupOrder = groupOrder;
+      }
       delete nextState.trashEntries[trashEntryId];
       delete nextState.deletedRecordTombstones[recordId];
       break;
@@ -3288,20 +3302,20 @@ const rtlHasValidRawCommittedWorkspace = (loaded, captured) => {
     !Object.prototype.hasOwnProperty.call(baseline, 'revision') ||
     !Object.prototype.hasOwnProperty.call(baseline, 'changeCursor') ||
     !rtlHasCompleteBaselineState(baseline.state) ||
-    !rtlRawNonNegativeSafeInteger(baseline.revision) ||
-    baseline.revision <= 0) {
-    return false;
-  }
-  if (!rtlResumeIdentityMatches(
-    baseline.changeCursor,
-    captured,
-    ownerUid,
-    loaded.workspaceEpoch
-  )) {
+    !rtlRawNonNegativeSafeInteger(baseline.revision)) {
     return false;
   }
   if (loaded.syncMeta !== undefined &&
     !rtlDurableIsObject(loaded.syncMeta)) return false;
+  if (typeof baseline.changeCursor !== 'string' ||
+    !rtlResumeIdentityMatches(
+      loaded.syncMeta?.changeCursorBinding,
+      captured,
+      ownerUid,
+      loaded.workspaceEpoch
+    )) {
+    return false;
+  }
   const resumeMarker = loaded.syncMeta?.resumeMarker ??
     loaded.syncMeta?.resume ??
     loaded.syncMeta?.bootstrapMarker;
@@ -3358,11 +3372,54 @@ const rtlStripSessionTokens = (value) => {
   const result = {};
   Object.entries(value).forEach(([key, entry]) => {
     if (rtlIsCredentialKey(key)) return;
-    result[key] = rtlStripSessionTokens(entry);
+    Object.defineProperty(result, key, {
+      value: rtlStripSessionTokens(entry),
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
   });
   return result;
 };
 
+// Domain state and operation payloads are opaque to Core. They may legitimately
+// contain fields such as `designToken` or `session` that are part of the user's
+// data, so the session-secret scrubber is limited to Core-owned envelopes.
+const rtlSanitizeDurableOperation = (operation) => {
+  const sanitized = rtlStripSessionTokens(operation);
+  if (rtlDurableIsObject(operation) &&
+    Object.prototype.hasOwnProperty.call(operation, 'payload')) {
+    sanitized.payload = clone(operation.payload);
+  }
+  return sanitized;
+};
+
+const rtlSanitizeDurableWorkspace = (workspace) => {
+  const sanitized = rtlStripSessionTokens(workspace);
+  if (!rtlDurableIsObject(workspace)) return sanitized;
+  if (rtlDurableIsObject(workspace.remoteBaseline) &&
+    Object.prototype.hasOwnProperty.call(workspace.remoteBaseline, 'state')) {
+    sanitized.remoteBaseline = {
+      ...sanitized.remoteBaseline,
+      state: clone(workspace.remoteBaseline.state)
+    };
+  }
+  if (Array.isArray(workspace.pendingOperations)) {
+    sanitized.pendingOperations = workspace.pendingOperations.map(rtlSanitizeDurableOperation);
+  }
+  if (rtlDurableIsObject(workspace.rejectedOperations)) {
+    sanitized.rejectedOperations = {...sanitized.rejectedOperations};
+    Object.entries(workspace.rejectedOperations).forEach(([id, entry]) => {
+      if (!rtlDurableIsObject(entry) || !rtlDurableIsObject(entry.operation)) return;
+      sanitized.rejectedOperations[id] = {
+        ...sanitized.rejectedOperations[id],
+        operation: rtlSanitizeDurableOperation(entry.operation)
+      };
+    });
+  }
+  return sanitized;
+};
+
 const rtlNormalizeOperation = (operation = {}, {
   client,
   clientId,
@@ -3389,7 +3446,7 @@ const rtlNormalizeOperation = (operation = {}, {
     ...rtlStripSessionTokens(input),
     // Preserve supplied IDs byte-for-byte.  Validation/quarantine must see an
     // invalid whitespace or hostile ID instead of receiving a silently rewritten one.
-    id: Object.prototype.hasOwnProperty.call(input, 'id') ? input.id : generatedId,
+    id: input.id === null || input.id === undefined ? generatedId : input.id,
     type: typeof input.type === 'string' ? input.type.trim() : input.type,
     payload: normalizedPayload,
     clientId: resolvedClientId,
@@ -3441,6 +3498,72 @@ const rtlEmptyDurableWorkspace = ({ownerUid = null, workspaceEpoch = 0} = {}) =>
   syncMeta: {}
 });
 
+const RTL_BOOTSTRAP_RESUME_META_KEYS = [
+  'resumeMarker',
+  'resume',
+  'bootstrapMarker',
+  'authSessionBinding',
+  'changeCursorBinding'
+];
+
+const rtlForceOperationIdentity = (operation, ownerUid, workspaceEpoch, options = {}) => ({
+  ...rtlNormalizePendingOperation(operation, {
+    ...options,
+    ownerUid,
+    workspaceEpoch
+  }),
+  ownerUid: rtlNormalizeUid(ownerUid),
+  workspaceEpoch: rtlNormalizeWorkspaceEpoch(workspaceEpoch, 0)
+});
+
+const rtlClearBootstrapResumeMeta = (syncMeta) => {
+  const next = rtlDurableIsObject(syncMeta) ? {...syncMeta} : {};
+  RTL_BOOTSTRAP_RESUME_META_KEYS.forEach((key) => {
+    delete next[key];
+  });
+  return next;
+};
+
+const rtlRebindSameOwnerWorkspaceEpoch = (workspace, captured, now) => {
+  const ownerUid = rtlNormalizeUid(captured?.uid);
+  const workspaceEpoch = rtlNormalizeWorkspaceEpoch(captured?.workspaceEpoch, 0);
+  const next = clone(workspace);
+  next.ownerUid = ownerUid;
+  next.workspaceEpoch = workspaceEpoch;
+  next.pendingOperations = toArray(next.pendingOperations).map((operation) => (
+    rtlForceOperationIdentity(operation, ownerUid, workspaceEpoch, {now})
+  ));
+  if (rtlDurableIsObject(next.rejectedOperations)) {
+    const rejected = {};
+    Object.entries(next.rejectedOperations).forEach(([id, entry]) => {
+      const value = rtlDurableIsObject(entry) ? {...entry} : entry;
+      if (rtlDurableIsObject(value) && value.operation) {
+        value.operation = rtlForceOperationIdentity(
+          value.operation,
+          ownerUid,
+          workspaceEpoch,
+          {now}
+        );
+      }
+      Object.defineProperty(rejected, id, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    });
+    next.rejectedOperations = rejected;
+  }
+  next.remoteBaseline = {
+    ...(rtlDurableIsObject(next.remoteBaseline)
+      ? next.remoteBaseline
+      : rtlNormalizeRemoteBaseline({})),
+    changeCursor: null
+  };
+  next.syncMeta = rtlClearBootstrapResumeMeta(next.syncMeta);
+  return next;
+};
+
 const rtlNormalizeDurableWorkspace = (input = {}, options = {}) => {
   const source = rtlDurableIsObject(input) ? input : {};
   const legacy = !source.remoteBaseline && (
@@ -3479,7 +3602,12 @@ const rtlNormalizeDurableWorkspace = (input = {}, options = {}) => {
   Object.entries(rejectedSource).forEach(([rawId, value]) => {
     const id = normalizeId(rawId || value?.id || value?.operationId);
     if (!id) return;
-    rejectedOperations[id] = clone(value && typeof value === 'object' ? value : {reason: value});
+    Object.defineProperty(rejectedOperations, id, {
+      value: clone(value && typeof value === 'object' ? value : {reason: value}),
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
     if (rejectedOperations[id].operation) {
       rejectedOperations[id].operation = rtlNormalizePendingOperation(
         rejectedOperations[id].operation,
@@ -3506,11 +3634,13 @@ const rtlNormalizeDurableWorkspace = (input = {}, options = {}) => {
 const rtlOperationIdentityReason = (operation, workspace) => {
   const candidateIds = [
     operation?.id,
+    operation?.payload?.id,
     operation?.payload?.recordId,
     operation?.payload?.folderId,
     operation?.payload?.targetFolderId,
     operation?.payload?.trashEntryId,
     operation?.payload?.record?.id,
+    operation?.payload?.record?.folderId,
     operation?.payload?.folder?.id,
     ...(Array.isArray(operation?.payload?.recordIds) ? operation.payload.recordIds : []),
     ...(Array.isArray(operation?.payload?.folderOrder) ? operation.payload.folderOrder : [])
@@ -3651,7 +3781,8 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
     }
     rejectedCount += 1;
     const rejectedId = id || `identity-rejected:${timestamp}:${index}`;
-    rejected[rejectedId] = {
+    Object.defineProperty(rejected, rejectedId, {
+      value: {
       id: rejectedId,
       operation: clone(operation),
       status: 'rejected',
@@ -3666,7 +3797,11 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
         ),
         workspaceEpoch: rtlNormalizeWorkspaceEpoch(workspace?.workspaceEpoch, 0)
       }
-    };
+      },
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
   });
   return {accepted, rejected, rejectedCount, deduplicatedCount};
 };
@@ -3741,8 +3876,6 @@ const rtlEnvelopePayload = (value) => {
     return candidate;
   };
   if (value && typeof value === 'object') {
-    if (value.remoteBaseline) return normalizeRevisionAlias(value.remoteBaseline);
-    if (value.baseline) return normalizeRevisionAlias(value.baseline);
     // A canonical failure may carry an authoritative baseline for an
     // operation-id conflict.  It must win over compatibility state fields
     // left beside `failure`; otherwise a stale outer state can be applied
@@ -3751,6 +3884,8 @@ const rtlEnvelopePayload = (value) => {
       const nested = rtlEnvelopePayload(value.failure);
       if (nested) return nested;
     }
+    if (value.remoteBaseline) return normalizeRevisionAlias(value.remoteBaseline);
+    if (value.baseline) return normalizeRevisionAlias(value.baseline);
     if (
       value.state !== undefined ||
       value.data !== undefined ||
@@ -3980,17 +4115,20 @@ export const createRecordTimeLabelSyncEngine = ({
   const persist = async (candidate, captured) => {
     if (!(await isCurrent(captured))) return false;
     const cursor = candidate?.remoteBaseline?.changeCursor;
+    candidate.syncMeta = rtlDurableIsObject(candidate.syncMeta)
+      ? {...candidate.syncMeta}
+      : {};
     if (cursor !== null && cursor !== undefined) {
-      const durableCursor = rtlDurableIsObject(cursor) ? clone(cursor) : {value: String(cursor)};
-      candidate.remoteBaseline.changeCursor = {
-        ...durableCursor,
+      candidate.syncMeta.changeCursorBinding = {
         ownerUid: captured?.uid ?? null,
         uid: captured?.uid ?? null,
         workspaceEpoch: captured?.workspaceEpoch ?? candidate.workspaceEpoch,
         authSessionBinding: captured?.authSessionBinding ?? null
       };
+    } else {
+      delete candidate.syncMeta.changeCursorBinding;
     }
-    const durableCandidate = rtlStripSessionTokens(candidate);
+    const durableCandidate = rtlSanitizeDurableWorkspace(candidate);
     // The second argument is an optional adapter-side fence.  The public
     // StoragePort remains compatible with save(workspace); adapters that can
     // enforce an atomic session/epoch check should consume this context before
@@ -4284,7 +4422,17 @@ export const createRecordTimeLabelSyncEngine = ({
     const epochMismatch = Boolean(
       captured?.hasEpoch && Number(loadedWorkspace.workspaceEpoch) !== Number(currentEpoch)
     );
-    if (ownerMismatch || epochMismatch) {
+    if (ownerMismatch) {
+      return rtlEmptyDurableWorkspace({ownerUid: currentUid, workspaceEpoch: currentEpoch});
+    }
+    if (epochMismatch) {
+      if (
+        sourceOwnerUid &&
+        sourceOwnerUid === currentUid &&
+        Number(currentEpoch) > Number(loadedWorkspace.workspaceEpoch)
+      ) {
+        return rtlRebindSameOwnerWorkspaceEpoch(loadedWorkspace, captured, now);
+      }
       return rtlEmptyDurableWorkspace({ownerUid: currentUid, workspaceEpoch: currentEpoch});
     }
     const currentView = Array.isArray(loadedWorkspace.syncMeta?.migratedExpandedGroups)
@@ -4358,6 +4506,30 @@ export const createRecordTimeLabelSyncEngine = ({
     ...extra
   });
 
+  const persistHydrationBarrier = async (captured, extraMeta = {}) => {
+    hydrationRequired = true;
+    const candidate = clone(workspace);
+    candidate.syncMeta = {
+      ...candidate.syncMeta,
+      hydrationRequired: true,
+      ...extraMeta
+    };
+    if (!(await persist(candidate, captured))) return false;
+    workspace = candidate;
+    return true;
+  };
+
+  const clearPersistedHydrationBarrier = (candidate) => {
+    if (!rtlDurableIsObject(candidate?.syncMeta) ||
+      !Object.prototype.hasOwnProperty.call(candidate.syncMeta, 'hydrationRequired')) {
+      return candidate;
+    }
+    const nextMeta = {...candidate.syncMeta};
+    delete nextMeta.hydrationRequired;
+    candidate.syncMeta = nextMeta;
+    return candidate;
+  };
+
   const persistTerminalFailureBlock = async ({
     failure,
     error,
@@ -4393,6 +4565,13 @@ export const createRecordTimeLabelSyncEngine = ({
     identityRejectedCount
   }) => {
     hydrationRequired = true;
+    if (!(await persistHydrationBarrier(captured, {
+      lastSyncAttemptAt: timestamp,
+      lastSyncFailure: clone(failure),
+      lastSyncError: failure.message || failure.code || 'bootstrap-required'
+    }))) {
+      return {success: false, reason: 'stale_session'};
+    }
     if (typeof cloud?.bootstrap !== 'function') {
       return failureOutcome(failure, error, {
         bootstrapRequired: true,
@@ -4431,6 +4610,7 @@ export const createRecordTimeLabelSyncEngine = ({
     candidate.syncMeta.lastSyncFailure = clone(failure);
     candidate.syncMeta.lastSyncAttemptAt = timestamp;
     candidate.syncMeta.lastSyncError = null;
+    clearPersistedHydrationBarrier(candidate);
     if (!(await persist(candidate, captured))) return {success: false, reason: 'stale_session'};
     workspace = candidate;
     hydrationRequired = false;
@@ -4614,14 +4794,19 @@ export const createRecordTimeLabelSyncEngine = ({
       const completedOperations = [];
       ready.forEach((operation) => {
         const reason = failure.reason || failure.code || 'operation_id_conflict';
-        nextRejected[operation.id] = {
+        Object.defineProperty(nextRejected, operation.id, {
+          value: {
           id: operation.id,
           operation: clone(operation),
           status: 'rejected',
           reason,
           rejectedAt: timestamp,
           response: rejectionResponse
-        };
+          },
+          enumerable: true,
+          configurable: true,
+          writable: true
+        });
         rejectedResults.push({
           id: operation.id,
           operationId: operation.id,
@@ -4711,7 +4896,7 @@ export const createRecordTimeLabelSyncEngine = ({
     const remoteState = remote?.state ?? remote?.data;
     const revisionOnlyNotification = !rtlDurableIsObject(remoteState);
     if (remoteRevision > candidate.remoteBaseline.revision + 1 || revisionOnlyNotification) {
-      if (typeof cloud?.bootstrap !== 'function') {
+      if (typeof cloud?.catchUp !== 'function' && typeof cloud?.bootstrap !== 'function') {
         const failure = normalizeRecordTimeLabelCloudFailure({
           class: RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED,
           code: 'revision_gap',
@@ -4821,10 +5006,17 @@ export const createRecordTimeLabelSyncEngine = ({
 
   const resetForSessionIdentity = (captured) => {
     stopCloudSubscription();
-    workspace = rtlEmptyDurableWorkspace({
-      ownerUid: captured?.uid,
-      workspaceEpoch: captured?.workspaceEpoch
-    });
+    const sameOwner = Boolean(
+      rtlNormalizeUid(workspace.ownerUid) &&
+      rtlNormalizeUid(workspace.ownerUid) === rtlNormalizeUid(captured?.uid)
+    );
+    const epochIncreased = Number(captured?.workspaceEpoch) > Number(workspace.workspaceEpoch);
+    workspace = sameOwner && epochIncreased
+      ? rtlRebindSameOwnerWorkspaceEpoch(workspace, captured, now)
+      : rtlEmptyDurableWorkspace({
+        ownerUid: captured?.uid,
+        workspaceEpoch: captured?.workspaceEpoch
+      });
     initialized = false;
     hydrationRequired = true;
     notify({type: 'session_changed'});
@@ -4857,6 +5049,7 @@ export const createRecordTimeLabelSyncEngine = ({
     let adapterReadyExpected = false;
     let firstCallbackResult = null;
     let firstRootObservation = null;
+    let latestRootObservationRevision = null;
     let adapterCatchUpProof = null;
     const settleReadyIfProven = () => {
       if (!isCurrentRemoteReady(readyState) || readyState.settled ||
@@ -4873,6 +5066,31 @@ export const createRecordTimeLabelSyncEngine = ({
       const caughtUpToRevision = Number.isSafeInteger(Number(proof.caughtUpToRevision))
         ? Number(proof.caughtUpToRevision)
         : revision;
+      if (revision < 0 || caughtUpToRevision < 0) {
+        readyState.reject(toRecordTimeLabelCloudFailureError({
+          class: RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL,
+          code: 'invalid_remote_ready_revision',
+          reason: 'invalid_remote_ready_revision',
+          message: 'invalid_remote_ready_revision'
+        }));
+        return;
+      }
+      const observedRevision = Number.isSafeInteger(latestRootObservationRevision)
+        ? latestRootObservationRevision
+        : baselineRevision;
+      const requiredRevision = Math.max(baselineRevision, observedRevision);
+      if (revision < requiredRevision || caughtUpToRevision < requiredRevision) {
+        readyState.reject(toRecordTimeLabelCloudFailureError({
+          class: RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL,
+          code: 'stale_remote_ready_revision',
+          reason: 'stale_remote_ready_revision',
+          message: 'stale_remote_ready_revision'
+        }));
+        return;
+      }
+      // A proof for a revision the root listener has not processed yet must
+      // remain behind the barrier. A later root observation retries settling.
+      if (revision > requiredRevision || caughtUpToRevision > requiredRevision) return;
       readyState.resolve({
         sessionKey: proof.sessionKey ??
           context.sessionKey ??
@@ -4883,7 +5101,7 @@ export const createRecordTimeLabelSyncEngine = ({
         caughtUpToRevision
       });
     };
-    const handleRootObservation = async (result) => {
+    const handleRootObservation = async (result, observedRevision) => {
       if (!(await isCurrent(captured)) || !isCurrentRemoteReady(readyState)) return;
       if (result?.stale === true || result?.reason === 'stale_session') return;
       if (result?.success === false) {
@@ -4897,6 +5115,12 @@ export const createRecordTimeLabelSyncEngine = ({
         return;
       }
       firstRootObservation = result || {success: true};
+      if (Number.isSafeInteger(observedRevision) && observedRevision >= 0) {
+        latestRootObservationRevision = Math.max(
+          latestRootObservationRevision ?? 0,
+          observedRevision
+        );
+      }
       if (!adapterReadyExpected) {
         adapterCatchUpProof = {
           success: true,
@@ -4911,9 +5135,13 @@ export const createRecordTimeLabelSyncEngine = ({
       if (destroyed || !isCurrentRemoteReady(readyState)) {
         return Promise.resolve({success: false, stale: true, reason: 'stale_session'});
       }
+      const observedRevisionValue = Number(rtlEnvelopePayload(remoteValue)?.revision);
+      const observedRevision = Number.isSafeInteger(observedRevisionValue) && observedRevisionValue >= 0
+        ? observedRevisionValue
+        : null;
       const callbackResult = enqueue(() => processRemote(remoteValue, captured));
       if (!firstCallbackResult) firstCallbackResult = callbackResult;
-      callbackResult.then((result) => handleRootObservation(result)).catch((error) => {
+      callbackResult.then((result) => handleRootObservation(result, observedRevision)).catch((error) => {
         if (isCurrentRemoteReady(readyState) && !readyState.settled) {
           readyState.reject(error);
         }
@@ -4931,7 +5159,7 @@ export const createRecordTimeLabelSyncEngine = ({
     }
     unsubscribeCloud = typeof disposer === 'function'
       ? disposer
-      : (typeof disposer?.unsubscribe === 'function' ? disposer.unsubscribe : null);
+      : (typeof disposer?.unsubscribe === 'function' ? () => disposer.unsubscribe() : null);
     const onSubscriptionError = (error) => {
       if (!isCurrentRemoteReady(readyState)) return;
       stopCloudSubscription({settleReady: false});
@@ -4991,6 +5219,7 @@ export const createRecordTimeLabelSyncEngine = ({
     const loadedBaseline = loaded?.remoteBaseline;
     const committedRevision = Number(loadedBaseline?.revision);
     const hasValidCommittedBaseline = rtlHasValidRawCommittedWorkspace(loaded, captured);
+    const persistedHydrationRequired = loaded?.syncMeta?.hydrationRequired === true;
     let candidate = normalizeLoadedWorkspace(loaded, captured);
     const identityChecked = rtlQuarantineOperations(
       candidate,
@@ -5002,17 +5231,20 @@ export const createRecordTimeLabelSyncEngine = ({
     const context = rtlSessionContext(captured, candidate, client);
 
     const canReuseCommitted = initialBaseline === 'reuse-committed' &&
+      !persistedHydrationRequired &&
       captured?.uid && loadedOwnerUid === rtlNormalizeUid(captured.uid) &&
       hasValidCommittedBaseline &&
       candidate.ownerUid === rtlNormalizeUid(captured.uid) &&
       candidate.remoteBaseline.revision === committedRevision &&
       (!captured.hasEpoch || Number(candidate.workspaceEpoch) === Number(captured.workspaceEpoch));
+    let obtainedFreshBaseline = canReuseCommitted;
     if (captured?.uid && typeof cloud?.bootstrap === 'function' && !canReuseCommitted) {
       // Do not carry untrusted resume state into a fresh hydration attempt.
       // Only the bootstrap response may establish the next cursor/marker.
       candidate.remoteBaseline.changeCursor = null;
       candidate.syncMeta = {...candidate.syncMeta};
-      ['resumeMarker', 'resume', 'bootstrapMarker', 'authSessionBinding'].forEach((key) => {
+      ['resumeMarker', 'resume', 'bootstrapMarker', 'authSessionBinding', 'changeCursorBinding']
+        .forEach((key) => {
         delete candidate.syncMeta[key];
       });
       let bootstrap;
@@ -5023,15 +5255,41 @@ export const createRecordTimeLabelSyncEngine = ({
         ));
       } catch (error) {
         if (!(await isCurrent(captured))) return getSnapshot();
+        if (persistedHydrationRequired) {
+          candidate.syncMeta = {...candidate.syncMeta, hydrationRequired: true};
+          await persist(candidate, captured);
+        }
         rethrowClassifiedCloudFailure(captured, error);
       }
       if (!(await isCurrent(captured))) return getSnapshot();
-      applyRemoteBaseline(candidate, bootstrap);
+      const applied = applyRemoteBaseline(candidate, bootstrap);
+      if (applied.stale) {
+        candidate.syncMeta = {...candidate.syncMeta, hydrationRequired: true};
+        if (!(await persist(candidate, captured))) return getSnapshot();
+        workspace = candidate;
+        initialized = true;
+        hydrationRequired = true;
+        notify({type: 'initialized'});
+        return getSnapshot();
+      }
       delete candidate.syncMeta.terminalFailureBlock;
+      clearPersistedHydrationBarrier(candidate);
+      obtainedFreshBaseline = true;
+    }
+
+    if (persistedHydrationRequired && !obtainedFreshBaseline) {
+      candidate.syncMeta = {...candidate.syncMeta, hydrationRequired: true};
+      if (!(await persist(candidate, captured))) return getSnapshot();
+      workspace = candidate;
+      initialized = true;
+      hydrationRequired = true;
+      notify({type: 'initialized'});
+      return getSnapshot();
     }
 
     // Always persist the normalized durable shape before subscribing.  This
     // also makes legacy migration atomic from the engine's point of view.
+    clearPersistedHydrationBarrier(candidate);
     if (!(await persist(candidate, captured))) return getSnapshot();
     workspace = candidate;
     initialized = true;
@@ -5049,14 +5307,7 @@ export const createRecordTimeLabelSyncEngine = ({
             startCloudSubscription(current, workspace);
             return {success: true, tokenRefreshed: true};
           }
-          stopCloudSubscription();
-          workspace = rtlEmptyDurableWorkspace({
-            ownerUid: current.uid,
-            workspaceEpoch: current.workspaceEpoch
-          });
-          initialized = false;
-          hydrationRequired = true;
-          notify({type: 'session_changed'});
+          resetForSessionIdentity(current);
           return {success: true, sessionChanged: true};
         }).catch((error) => {
           logger?.error?.('[RecordTimeLabelCore] durable session callback failed', error);
@@ -5388,14 +5639,19 @@ export const createRecordTimeLabelSyncEngine = ({
         nextPending.push(makeRetryOperation(operation, result, null, timestamp));
       } else if (result.status === 'rejected') {
         completedOperations.push({operation, status: result.status});
-        nextRejected[operation.id] = {
+        Object.defineProperty(nextRejected, operation.id, {
+          value: {
           id: operation.id,
           operation: clone(operation),
           status: 'rejected',
           reason: result.reason ?? result.error ?? result.code ?? 'rejected',
           rejectedAt: timestamp,
           response: rtlStripSessionTokens(result)
-        };
+          },
+          enumerable: true,
+          configurable: true,
+          writable: true
+        });
       }
     }
     const responseState = responseBaseline?.state ?? responseBaseline?.data;
@@ -5930,8 +6186,8 @@ const rtlOperationRecordId = (operation = {}) => rtlFirstPresent(operation?.payl
   'recordId', 'id'
 ]) ?? operation?.payload?.record?.id ?? null;
 const rtlOperationFolderId = (operation = {}) => rtlFirstPresent(operation?.payload, [
-  'folderId', 'id'
-]) ?? operation?.payload?.folder?.id ?? null;
+  'targetFolderId', 'folderId', 'id'
+]) ?? operation?.payload?.folder?.id ?? operation?.payload?.record?.folderId ?? null;
 const rtlOperationTrashEntryId = (operation = {}) => rtlFirstPresent(operation?.payload, [
   'trashEntryId', 'id'
 ]) ?? null;
@@ -5990,6 +6246,19 @@ const rtlPayloadOrder = (operation, keys) => {
   }
   return [];
 };
+// Partial delete reads omit sibling records, so folder.recordOrder is the live slot.
+const rtlResolveOriginalRecordIndex = (payload, existingRecord, folders) => {
+  if (Number.isInteger(payload?.originalRecordIndex) && payload.originalRecordIndex >= 0) {
+    return payload.originalRecordIndex;
+  }
+  const recordId = normalizeId(existingRecord?.id);
+  const folderId = safeFolderId(existingRecord?.folderId || payload?.folderId);
+  const recordOrder = rtlMergeOrder(
+    rtlOwn(folders, folderId) ? folders[folderId]?.recordOrder : []
+  );
+  const orderIndex = recordId ? recordOrder.indexOf(recordId) : -1;
+  return orderIndex >= 0 ? orderIndex : 0;
+};
 const rtlHasInvalidPayloadValue = (value, depth = 0) => {
   if (depth > 20) return true;
   if (typeof value === 'number') return !Number.isFinite(value);
@@ -6002,12 +6271,13 @@ const rtlHasInvalidPayloadValue = (value, depth = 0) => {
 };
 
 const rtlIsObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-const rtlValidateIdList = (value, index, field, errors) => {
+const rtlValidateIdList = (value, index, field, errors, {opaqueGroup = false} = {}) => {
   if (!Array.isArray(value)) {
     errors.push(`operation_${index}_invalid_${field}`);
     return;
   }
-  if (value.some((id) => !rtlIsSafeDocumentId(id))) {
+  const isValid = opaqueGroup ? rtlIsSafeOpaqueGroupId : rtlIsSafeDocumentId;
+  if (value.some((id) => !isValid(id))) {
     errors.push(`operation_${index}_invalid_${field}`);
   }
 };
@@ -6027,8 +6297,13 @@ const rtlValidateOperationPayload = (operation, index, errors, options = {}) =>
       break;
     case OPERATION_TYPES.RECORD_MOVE:
       if (!recordId) errors.push(`operation_${index}_missing_record_id`);
-      if (!normalizeId(payload.targetFolderId || payload.folderId)) {
-        errors.push(`operation_${index}_missing_target_folder_id`);
+      {
+        const targetFolderId = rtlFirstPresent(payload, ['targetFolderId', 'folderId']);
+        if (targetFolderId === undefined || targetFolderId === null) {
+          errors.push(`operation_${index}_missing_target_folder_id`);
+        } else if (!rtlIsSafeDocumentId(targetFolderId)) {
+          errors.push(`operation_${index}_invalid_target_folder_id`);
+        }
       }
       break;
     case OPERATION_TYPES.RECORD_DELETE:
@@ -6076,14 +6351,21 @@ const rtlValidateOperationPayload = (operation, index, errors, options = {}) =>
       rtlValidateIdList(payload.folderOrder || payload.order, index, 'folder_order', errors);
       break;
     case OPERATION_TYPES.GROUP_REORDER:
-      rtlValidateIdList(payload.groupOrder || payload.order, index, 'group_order', errors);
+      rtlValidateIdList(
+        payload.groupOrder || payload.order,
+        index,
+        'group_order',
+        errors,
+        {opaqueGroup: true}
+      );
       break;
     case OPERATION_TYPES.EXPANDED_GROUPS_UPDATE:
       rtlValidateIdList(
         payload.expandedGroups || payload.groupIds || payload.order || payload.ids,
         index,
         'expanded_groups',
-        errors
+        errors,
+        {opaqueGroup: true}
       );
       break;
     case OPERATION_TYPES.SETTINGS_UPDATE:
@@ -6503,8 +6785,17 @@ export const planFirestoreV2OperationChanges = ({
           reason = recordId ? 'record_not_found' : 'missing_record_id';
           break;
         }
+        const rawTargetFolderId = rtlFirstPresent(payload, ['targetFolderId', 'folderId']);
+        if (rawTargetFolderId === undefined || rawTargetFolderId === null) {
+          reason = 'missing_target_folder_id';
+          break;
+        }
+        if (!rtlIsSafeDocumentId(rawTargetFolderId)) {
+          reason = 'invalid_document_id';
+          break;
+        }
         const sourceFolderId = safeFolderId(existing.folderId);
-        const targetFolderId = safeFolderId(payload.targetFolderId || payload.folderId);
+        const targetFolderId = rawTargetFolderId;
         applied = rtlApplyOperationToPartialDocuments({
           ...nextDocuments,
           operation: {...operation, payload: {...payload, targetFolderId}},
@@ -6599,7 +6890,21 @@ export const planFirestoreV2OperationChanges = ({
           break;
         }
         const sourceFolderId = safeFolderId(existingRecord.folderId);
-        applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
+        applied = rtlApplyOperationToPartialDocuments({
+          ...nextDocuments,
+          operation: {
+            ...operation,
+            payload: {
+              ...payload,
+              originalRecordIndex: rtlResolveOriginalRecordIndex(
+                payload,
+                existingRecord,
+                nextDocuments.folders
+              )
+            }
+          },
+          now: operationNow
+        });
         rtlSetRoot(nextDocuments.root, applied.documents.root);
         const trashDocument = rtlOwn(applied.documents.trash, operationTrashEntryId)
           ? applied.documents.trash[operationTrashEntryId]

package/src/protocol.js

@@ -118,6 +118,7 @@ const CLOUD_FAILURE_CODE_CLASSES = new Map([
   ['bulk_job_in_progress', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['bootstrap_session_limit_exceeded', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['daily_bootstrap_read_limit_exceeded', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['global_bootstrap_read_limit_exceeded', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['rate_limited', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['too_many_requests', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['network_error', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
@@ -131,6 +132,9 @@ const CLOUD_FAILURE_CODE_CLASSES = new Map([
   ['cache_ahead', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
   ['changed_document_missing', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
   ['root_document_missing', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
+  ['firestore_v2_root_missing', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
+  ['firestore_v2_root_revision_missing', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
+  ['bootstrap_missing_root', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
   ['stale_session', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
   ['recordtimelabel_stale_session', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
   ['auth_context_changed', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
@@ -160,6 +164,11 @@ const CLOUD_FAILURE_CODE_CLASSES = new Map([
   ['lifecycle_generation_required', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
   ['record_not_found', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
   ['folder_not_found', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  // Snapshot workers consume this same classifier as HTTP clients. These
+  // states cannot become valid by retrying the immutable queued job.
+  ['snapshot_upload_binding_mismatch', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['snapshot_upload_changed_after_queue', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['invalid_snapshot_job_state', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
   ...[...OPERATION_CONFLICT_CODES].map((code) => [
     code,
     RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL