@recordtimelabel/core 0.6.10 → 0.6.12

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.9`; 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.12`; verify that its registry tarball and lockfile integrity are available before updating consumers:
 
 ```json
-"@recordtimelabel/core": "0.6.9"
+"@recordtimelabel/core": "0.6.12"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.

package/package.json

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

package/src/changefeed.js

@@ -1,3 +1,5 @@
+import {normalizeRecordTimeLabelImmutableId} from './protocol.js';
+
 export const FIRESTORE_V2_BOOTSTRAP_REASONS = Object.freeze({
   REVISION_GAP: 'revision-gap',
   REVISION_DUPLICATE: 'revision-duplicate',
@@ -8,16 +10,27 @@ export const FIRESTORE_V2_BOOTSTRAP_REASONS = Object.freeze({
   INVALID_CHANGE_CONFLICT: 'invalid-change-conflict'
 });
 
-const toId = (value) => String(value || '').trim();
-const toIdList = (value) => (Array.isArray(value) ? value : []).map(toId).filter(Boolean);
+const toId = (value) => normalizeRecordTimeLabelImmutableId(value);
+const toIdList = (value) => {
+  if (!Array.isArray(value)) return {ids: [], invalid: false};
+  const ids = [];
+  let invalid = false;
+  value.forEach((entry) => {
+    const id = toId(entry);
+    if (!id) invalid = true;
+    else ids.push(id);
+  });
+  return {ids, invalid};
+};
 
 const decodeLifecycleTombstoneId = (value) => {
-  const id = toId(value);
-  if (!id) return '';
+  if (typeof value !== 'string' || value.length === 0 || value !== value.trim()) return '';
+  const id = value;
   try {
-    return decodeURIComponent(id);
+    const decoded = decodeURIComponent(id);
+    return normalizeRecordTimeLabelImmutableId(decoded) || '';
   } catch {
-    return id;
+    return '';
   }
 };
 
@@ -29,7 +42,7 @@ export const lifecycleTombstoneDocumentKey = (value) => {
 export const lifecycleTombstoneKeyAliases = (value) => {
   const logicalId = decodeLifecycleTombstoneId(value);
   if (!logicalId) return [];
-  return [...new Set([toId(value), logicalId, encodeURIComponent(logicalId)].filter(Boolean))];
+  return [...new Set([value, logicalId, encodeURIComponent(logicalId)].filter(Boolean))];
 };
 
 const cloneDocuments = (documents = {}) => ({
@@ -164,7 +177,7 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
       ['trash', change?.changedTrashEntryIds, 'changed'],
       ['trash', change?.deletedTrashEntryIds, 'deleted']
     ].forEach(([kind, ids, mutation]) => {
-      toIdList(ids).forEach((id) => finalMutations[kind].set(id, {index, mutation}));
+      toIdList(ids).ids.forEach((id) => finalMutations[kind].set(id, {index, mutation}));
     });
   });
   const isShadowedByLaterDelete = (kind, id, index) => {
@@ -188,22 +201,34 @@ export const applyFirestoreV2ResolvedChangeBatch = ({
       return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.REVISION_OVERSHOOT, inputCache);
     }
 
-    const changedRecords = toIdList(change.changedRecordIds);
-    const deletedRecords = toIdList(change.deletedRecordIds);
-    const changedFolders = toIdList(change.changedFolderIds);
-    const deletedFolders = toIdList(change.deletedFolderIds);
-    const changedTrash = toIdList(change.changedTrashEntryIds);
-    const deletedTrash = toIdList(change.deletedTrashEntryIds);
+    const changedRecordsResult = toIdList(change.changedRecordIds);
+    const deletedRecordsResult = toIdList(change.deletedRecordIds);
+    const changedFoldersResult = toIdList(change.changedFolderIds);
+    const deletedFoldersResult = toIdList(change.deletedFolderIds);
+    const changedTrashResult = toIdList(change.changedTrashEntryIds);
+    const deletedTrashResult = toIdList(change.deletedTrashEntryIds);
+    const changedRecords = changedRecordsResult.ids;
+    const deletedRecords = deletedRecordsResult.ids;
+    const changedFolders = changedFoldersResult.ids;
+    const deletedFolders = deletedFoldersResult.ids;
+    const changedTrash = changedTrashResult.ids;
+    const deletedTrash = deletedTrashResult.ids;
     const lifecycleUpserts = Array.isArray(change.lifecycleTombstoneUpserts)
       ? change.lifecycleTombstoneUpserts
       : [];
-    const lifecycleDeletes = toIdList(change.deletedLifecycleTombstoneIds);
+    const lifecycleDeletesResult = toIdList(change.deletedLifecycleTombstoneIds);
+    const lifecycleDeletes = lifecycleDeletesResult.ids;
+    const lifecycleUpsertKeys = lifecycleUpserts.map((entry) => lifecycleTombstoneDocumentKey(entry?.id));
+    const hasInvalidId = [changedRecordsResult, deletedRecordsResult, changedFoldersResult,
+      deletedFoldersResult, changedTrashResult, deletedTrashResult, lifecycleDeletesResult]
+      .some((result) => result.invalid) || lifecycleUpsertKeys.some((key) => !key);
+    if (hasInvalidId) {
+      return fail(FIRESTORE_V2_BOOTSTRAP_REASONS.INVALID_CHANGE_CONFLICT, inputCache);
+    }
     const lifecycleUpsertIds = lifecycleUpserts
-      .map((entry) => lifecycleTombstoneDocumentKey(entry?.id))
-      .filter(Boolean);
+      .map((entry) => lifecycleTombstoneDocumentKey(entry?.id));
     const lifecycleDeleteIds = lifecycleDeletes
-      .map((id) => lifecycleTombstoneDocumentKey(id))
-      .filter(Boolean);
+      .map((id) => lifecycleTombstoneDocumentKey(id));
 
     if (
       hasConflict(changedRecords, deletedRecords) ||

package/src/index.js

@@ -7,6 +7,7 @@ import {
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
   RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CODE_LOCAL_STORAGE_QUOTA_EXCEEDED,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
   RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
@@ -33,6 +34,7 @@ export {
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
   RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CODE_LOCAL_STORAGE_QUOTA_EXCEEDED,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
   RECORD_TIMELABEL_CLOUD_RECOVERY_ACTIONS,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
@@ -145,7 +147,7 @@ export {
   selectBestMatchingTwitchVod
 };
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.6.10';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.6.12';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -602,6 +604,13 @@ export const applyExplicitRecordUpdate = (record = {}, patch = {}, operationTime
   return next;
 };
 
+// lifecycleGeneration is a Core-owned fence.  Payload snapshots are hints
+// only; they must never be able to lower a live entity or tombstone fence.
+const rtlMaxLifecycleGeneration = (...values) => values.reduce((max, value) => {
+  const generation = Number(value?.lifecycleGeneration ?? value);
+  return Number.isSafeInteger(generation) && generation > max ? generation : max;
+}, 0);
+
 export const normalizeRecords = (records = {}, options = {}) => {
   const source = records && typeof records === 'object' ? records : {};
   const tombstones = normalizeTombstones(options.deletedRecordTombstones);
@@ -1019,6 +1028,9 @@ export const applyOperation = (state = {}, operation = {}) => {
         id: recordId,
         updatedAt: record.updatedAt || operationTime
       };
+      cleanedRecord.lifecycleGeneration = rtlMaxLifecycleGeneration(
+        record, nextState.deletedRecordTombstones[recordId]
+      );
       delete cleanedRecord.folderId;
 
       nextState.records = removeRecordById(nextState.records, recordId);
@@ -1034,12 +1046,15 @@ export const applyOperation = (state = {}, operation = {}) => {
       if (!recordId || !rtlIsSafeDocumentId(recordId)) return normalized;
       const entry = findRecordEntry(nextState.records, recordId);
       if (!entry) return normalized;
-      const patch = payload.patch || payload.record || {};
+      const patch = {...(payload.patch || payload.record || {})};
+      delete patch.lifecycleGeneration;
       if (Object.keys(patch).some((key) => RTL_RESERVED_DOCUMENT_KEYS.has(key))) {
         return normalized;
       }
       const updatedRecord = applyExplicitRecordUpdate(entry.record, patch, operationTime);
       updatedRecord.id = recordId;
+      updatedRecord.lifecycleGeneration = rtlMaxLifecycleGeneration(entry.record,
+        nextState.deletedRecordTombstones[recordId]);
       nextState.records[entry.folderId][entry.index] = updatedRecord;
       break;
     }
@@ -1058,6 +1073,8 @@ export const applyOperation = (state = {}, operation = {}) => {
         id: recordId,
         updatedAt: payload.updatedAt || operationTime
       };
+      movedRecord.lifecycleGeneration = rtlMaxLifecycleGeneration(entry.record,
+        nextState.deletedRecordTombstones[recordId]);
       nextState.records = removeRecordById(nextState.records, recordId);
       nextState.records[targetFolderId] = [
         ...toArray(nextState.records[targetFolderId]),
@@ -1131,13 +1148,13 @@ export const applyOperation = (state = {}, operation = {}) => {
         return normalized;
       }
       if (recordSnapshot && existingTombstone && Number(existingTombstone.lifecycleGeneration || 0) >=
-        Number(recordSnapshot.lifecycleGeneration || 0)) {
+        rtlMaxLifecycleGeneration(recordSnapshot, existingEntry?.record)) {
         return normalized;
       }
       const deletedAt = toFiniteTimestamp(payload.deletedAt) || operationTime;
-      const previousGeneration = Math.max(
-        Number(recordSnapshot?.lifecycleGeneration || 0),
-        Number(nextState.deletedRecordTombstones[recordId]?.lifecycleGeneration || 0)
+      const previousGeneration = rtlMaxLifecycleGeneration(
+        existingEntry?.record, recordSnapshot,
+        nextState.deletedRecordTombstones[recordId]
       );
       const lifecycleGeneration = previousGeneration + 1;
       if (recordSnapshot) {
@@ -1254,10 +1271,14 @@ export const applyOperation = (state = {}, operation = {}) => {
     case OPERATION_TYPES.FOLDER_UPDATE: {
       const folderId = normalizeId(payload.folderId || payload.id || payload.folder?.id);
       if (!folderId || !rtlIsSafeDocumentId(folderId)) return normalized;
-      const patch = payload.patch || payload.folder || {};
+      const patch = {...(payload.patch || payload.folder || {})};
+      delete patch.lifecycleGeneration;
       nextState.folders = nextState.folders.map((folder) => (
         folder.id === folderId
-          ? { ...folder, ...patch, id: folderId, updatedAt: patch.updatedAt || operationTime }
+          ? { ...folder, ...patch, id: folderId,
+            lifecycleGeneration: rtlMaxLifecycleGeneration(folder,
+              nextState.deletedFolderTombstones[folderId]),
+            updatedAt: patch.updatedAt || operationTime }
           : folder
       ));
       break;
@@ -1271,6 +1292,14 @@ export const applyOperation = (state = {}, operation = {}) => {
         ? {...payload.folder, id: folderId}
         : nextState.folders.find((folder) => folder.id === folderId);
       const folderRecords = toArray(payload.records || nextState.records[folderId]).map((record) => ({...record}));
+      const liveRecordsById = new Map(toArray(nextState.records[folderId])
+        .map((record) => [getRecordId(record), record]));
+      folderRecords.forEach((record) => {
+        const recordId = getRecordId(record);
+        record.lifecycleGeneration = rtlMaxLifecycleGeneration(
+          record, liveRecordsById.get(recordId), nextState.deletedRecordTombstones[recordId]
+        );
+      });
       const existingTombstone = rtlOwn(nextState.deletedFolderTombstones, folderId)
         ? nextState.deletedFolderTombstones[folderId]
         : null;
@@ -1280,13 +1309,14 @@ export const applyOperation = (state = {}, operation = {}) => {
         return normalized;
       }
       if (folderSnapshot && existingTombstone && Number(existingTombstone.lifecycleGeneration || 0) >=
-        Number(folderSnapshot.lifecycleGeneration || 0)) {
+        rtlMaxLifecycleGeneration(folderSnapshot,
+          nextState.folders.find((folder) => folder.id === folderId))) {
         return normalized;
       }
       const deletedAt = toFiniteTimestamp(payload.deletedAt) || operationTime;
-      const previousGeneration = Math.max(
-        Number(folderSnapshot?.lifecycleGeneration || 0),
-        Number(nextState.deletedFolderTombstones[folderId]?.lifecycleGeneration || 0)
+      const previousGeneration = rtlMaxLifecycleGeneration(
+        nextState.folders.find((folder) => folder.id === folderId), folderSnapshot,
+        nextState.deletedFolderTombstones[folderId]
       );
       const lifecycleGeneration = previousGeneration + 1;
       if (folderSnapshot) {
@@ -1370,7 +1400,16 @@ export const applyOperation = (state = {}, operation = {}) => {
         lifecycleGeneration,
         updatedAt: operationTime
       });
-      nextState.records[folderId] = toArray(trashEntry.payload?.records).map((record) => ({
+      const restorableRecords = toArray(trashEntry.payload?.records).filter((record) => {
+        const recordId = getRecordId(record);
+        if (!recordId) return false;
+        const tombstone = nextState.deletedRecordTombstones[recordId];
+        // A child tombstone may have advanced after the folder delete.  It is
+        // no longer proven to belong to this restore and must be preserved.
+        return tombstone && Number(tombstone.lifecycleGeneration) ===
+          Number(record.lifecycleGeneration || 0);
+      });
+      nextState.records[folderId] = restorableRecords.map((record) => ({
         ...record,
         lifecycleGeneration: Number(record.lifecycleGeneration || 0) + 1,
         updatedAt: operationTime
@@ -1923,6 +1962,12 @@ const cleanV2RecordDocument = (record = {}, folderId, now) => {
   const cleanRecord = { ...record, id: recordId, folderId: safeFolderId(folderId) };
   delete cleanRecord.pendingSync;
   delete cleanRecord.syncAttempts;
+  // Keep the zero fence explicit so deterministic and incremental planners
+  // serialize a newly-created record identically.
+  cleanRecord.lifecycleGeneration = Number.isSafeInteger(Number(cleanRecord.lifecycleGeneration)) &&
+    Number(cleanRecord.lifecycleGeneration) >= 0
+    ? Number(cleanRecord.lifecycleGeneration)
+    : 0;
   return {
     ...cleanRecord,
     updatedAt: cleanRecord.updatedAt || cleanRecord.createdAt || now,
@@ -3475,6 +3520,9 @@ const rtlSanitizeDurableWorkspace = (workspace) => {
       state: clone(workspace.remoteBaseline.state)
     };
   }
+  if (rtlDurableIsObject(workspace.localState)) {
+    sanitized.localState = clone(workspace.localState);
+  }
   if (Array.isArray(workspace.pendingOperations)) {
     sanitized.pendingOperations = workspace.pendingOperations.map(rtlSanitizeDurableOperation);
   }
@@ -3559,6 +3607,22 @@ const rtlNormalizeRemoteBaseline = (value = {}) => {
   };
 };
 
+// Full-state baseline ingress is fail-closed.  Normalization is intentionally
+// only used after this admission check; otherwise missing collections would
+// be silently replaced with empty defaults and could erase committed data.
+const rtlIsAdmissibleRemoteBaseline = (value) => {
+  if (!rtlDurableIsObject(value)) return false;
+  const state = value.state ?? value.data;
+  if (!rtlHasCompleteBaselineState(state)) return false;
+  if (!rtlRawNonNegativeSafeInteger(value.revision)) return false;
+  if (Object.prototype.hasOwnProperty.call(value, 'changeCursor')) {
+    const cursor = value.changeCursor;
+    if (cursor !== null && cursor !== undefined &&
+      typeof cursor !== 'string' && !rtlDurableIsObject(cursor)) return false;
+  }
+  return true;
+};
+
 const rtlEmptyDurableWorkspace = ({ownerUid = null, workspaceEpoch = 0} = {}) => ({
   schemaVersion: RTL_DURABLE_SCHEMA_VERSION,
   ownerUid: rtlNormalizeUid(ownerUid),
@@ -3646,7 +3710,8 @@ const rtlNormalizeDurableWorkspace = (input = {}, options = {}) => {
     source.workspaceEpoch ?? options.workspaceEpoch,
     options.workspaceEpoch
   );
-  const baseline = legacy
+  const localOnly = source.localOnly === true;
+  const baseline = localOnly ? null : legacy
     ? rtlNormalizeRemoteBaseline({
       state: source.state || {},
       revision: source.revision ?? source.syncMeta?.revision,
@@ -3690,7 +3755,11 @@ const rtlNormalizeDurableWorkspace = (input = {}, options = {}) => {
     schemaVersion: RTL_DURABLE_SCHEMA_VERSION,
     ownerUid,
     workspaceEpoch,
-    remoteBaseline: baseline,
+    ...(localOnly
+      ? {localOnly: true, localState: normalizeRecordTimeLabelDomainState(
+        source.localState ?? source.state ?? {}
+      )}
+      : {remoteBaseline: baseline}),
     pendingOperations,
     rejectedOperations,
     syncMeta: {
@@ -3819,7 +3888,9 @@ const rtlQuarantineOperations = (workspace, operations, timestamp = Date.now())
     }
   });
   let lifecycleState = operations === workspace?.pendingOperations
-    ? normalizeRecordTimeLabelDomainState(workspace?.remoteBaseline?.state || {})
+    ? normalizeRecordTimeLabelDomainState(
+      workspace?.localOnly ? workspace?.localState || {} : workspace?.remoteBaseline?.state || {}
+    )
     : rtlDeriveDurableVisibleState(workspace);
   if (operations !== workspace?.pendingOperations) {
     toArray(workspace?.pendingOperations).forEach((operation) => {
@@ -3895,13 +3966,22 @@ const rtlExtractSession = (session, fallbackEpoch = 0) => {
   const authSessionBinding = current && typeof current === 'object'
     ? (current.authSessionBinding ?? current.authSessionId ?? current.authSessionKey ?? null)
     : null;
-  const uid = rtlNormalizeUid(current && typeof current === 'object'
-    ? (current.uid ?? current.ownerUid)
+  const rawLocalOnly = Boolean(current && typeof current === 'object' && current.localOnly === true);
+  const uid = rawLocalOnly
+    ? null
+    : rtlNormalizeUid(current && typeof current === 'object'
+      ? (current.uid ?? current.ownerUid)
+      : null);
+  const retainedOwnerUid = rtlNormalizeUid(current && typeof current === 'object'
+    ? (current.retainedOwnerUid ?? current.ownerUid ?? current.uid)
     : null);
   const rawEpoch = current && typeof current === 'object'
     ? (current.workspaceEpoch ?? current.epoch)
     : undefined;
   const hasEpoch = rawEpoch !== undefined && rawEpoch !== null && Number.isFinite(Number(rawEpoch));
+  const localOnly = rawLocalOnly;
+  const allowHydrationDispatch = Boolean(current && typeof current === 'object' &&
+    current.allowHydrationDispatch === true);
   return {
     current,
     hasSession: typeof session?.current === 'function',
@@ -3910,6 +3990,9 @@ const rtlExtractSession = (session, fallbackEpoch = 0) => {
       ? authSessionBinding
       : null,
     uid,
+    retainedOwnerUid,
+    localOnly,
+    allowHydrationDispatch,
     workspaceEpoch: hasEpoch
       ? rtlNormalizeWorkspaceEpoch(rawEpoch, fallbackEpoch)
       : rtlNormalizeWorkspaceEpoch(fallbackEpoch, 0),
@@ -4057,7 +4140,9 @@ const rtlIsStaleRevision = (revision, baselineRevision) => (
 );
 
 const rtlDeriveDurableVisibleState = (workspace) => {
-  let state = normalizeRecordTimeLabelDomainState(workspace?.remoteBaseline?.state || {});
+  let state = normalizeRecordTimeLabelDomainState(
+    workspace?.localOnly ? workspace?.localState || {} : workspace?.remoteBaseline?.state || {}
+  );
   toArray(workspace?.pendingOperations).forEach((operation) => {
     state = operation?.type === OPERATION_TYPES.EXPANDED_GROUPS_UPDATE
       ? state
@@ -4156,7 +4241,10 @@ export const createRecordTimeLabelSyncEngine = ({
 
   const workspaceMatchesSession = (captured) => {
     if (!captured?.hasSession) return true;
-    return rtlNormalizeUid(workspace.ownerUid) === captured.uid &&
+    const effectiveUid = captured.localOnly
+      ? (captured.retainedOwnerUid || captured.uid)
+      : captured.uid;
+    return rtlNormalizeUid(workspace.ownerUid) === effectiveUid &&
       Number(workspace.workspaceEpoch) === Number(captured.workspaceEpoch);
   };
 
@@ -4164,9 +4252,12 @@ export const createRecordTimeLabelSyncEngine = ({
     if (destroyed || !captured) return false;
     if (typeof session?.isCurrent === 'function') {
       try {
+        const effectiveUid = captured.localOnly
+          ? (captured.retainedOwnerUid || captured.uid)
+          : captured.uid;
         return Boolean(await session.isCurrent(
           captured.sessionToken,
-          captured.uid,
+          effectiveUid,
           captured.workspaceEpoch
         ));
       } catch {
@@ -4218,6 +4309,10 @@ export const createRecordTimeLabelSyncEngine = ({
   const applyRemoteBaseline = (candidate, remoteValue) => {
     const remote = rtlEnvelopePayload(remoteValue);
     if (!remote) return {changed: false, stale: false};
+    if ((remote.state ?? remote.data) !== undefined &&
+      !rtlIsAdmissibleRemoteBaseline(remote)) {
+      return {changed: false, stale: false, invalid: true};
+    }
     const revision = Number(remote.revision);
     if (rtlIsStaleRevision(revision, candidate.remoteBaseline.revision)) {
       return {changed: false, stale: true};
@@ -4301,10 +4396,26 @@ export const createRecordTimeLabelSyncEngine = ({
       throw toRecordTimeLabelCloudFailureError(source);
     }
     const remote = rtlEnvelopePayload(response);
-    const revision = Number(remote?.revision);
-    const state = remote?.state ?? remote?.data;
-    if (!remote || !rtlDurableIsObject(state) ||
-      !Number.isSafeInteger(revision) || revision < 0) {
+    if (remote?.localOnly === true) {
+      const localState = remote.state ?? remote.data;
+      if (!rtlDurableIsObject(localState)) {
+        throw toRecordTimeLabelCloudFailureError({
+          code: 'recordtimelabel_invalid_local_only_bootstrap',
+          reason: 'recordtimelabel_invalid_local_only_bootstrap',
+          message: 'recordtimelabel_invalid_local_only_bootstrap',
+          retryable: false
+        });
+      }
+      return {
+        localOnly: true,
+        localState: normalizeRecordTimeLabelDomainState(localState),
+        revision: Number.isSafeInteger(Number(remote.revision)) && Number(remote.revision) >= 0
+          ? Number(remote.revision)
+          : 0,
+        changeCursor: remote.changeCursor ?? null
+      };
+    }
+    if (!rtlIsAdmissibleRemoteBaseline(remote)) {
       throw toRecordTimeLabelCloudFailureError({
         code: 'recordtimelabel_invalid_bootstrap_response',
         reason: 'recordtimelabel_invalid_bootstrap_response',
@@ -4312,7 +4423,11 @@ export const createRecordTimeLabelSyncEngine = ({
         retryable: false
       });
     }
-    return {state, revision, changeCursor: remote.changeCursor ?? null};
+    return {
+      state: remote.state ?? remote.data,
+      revision: remote.revision,
+      changeCursor: remote.changeCursor ?? null
+    };
   };
 
   // A transient failure belongs to the same logical page walk. Keep its
@@ -4469,7 +4584,9 @@ export const createRecordTimeLabelSyncEngine = ({
         now
       }
     );
-    const currentUid = captured?.uid;
+    const currentUid = captured?.localOnly
+      ? (captured?.retainedOwnerUid || captured?.ownerUid || null)
+      : captured?.uid;
     const currentEpoch = captured?.workspaceEpoch ?? loadedWorkspace.workspaceEpoch;
     const anonymousMigration = Boolean(
       currentUid &&
@@ -4478,7 +4595,9 @@ export const createRecordTimeLabelSyncEngine = ({
       !loadedWorkspace.syncMeta?.anonymousMigrationAt
     );
     if (anonymousMigration) {
-      const anonymousState = loadedWorkspace.remoteBaseline.state;
+      const anonymousState = loadedWorkspace.localOnly
+        ? loadedWorkspace.localState
+        : loadedWorkspace.remoteBaseline.state;
       const migrationTime = Math.max(1, rtlToFiniteNumber(anonymousState.lastModified, now()));
       const migratedOperations = [];
       const seenIds = new Set();
@@ -4580,9 +4699,13 @@ export const createRecordTimeLabelSyncEngine = ({
       loadedWorkspace.pendingOperations.length ||
       Object.prototype.hasOwnProperty.call(loadedWorkspace.syncMeta || {}, 'legacyExpandedGroups');
     loadedWorkspace.pendingOperations = migratedView.pendingOperations;
-    loadedWorkspace.remoteBaseline.state = normalizeRecordTimeLabelDomainState(
-      loadedWorkspace.remoteBaseline.state
-    );
+    if (loadedWorkspace.localOnly) {
+      loadedWorkspace.localState = normalizeRecordTimeLabelDomainState(loadedWorkspace.localState);
+    } else {
+      loadedWorkspace.remoteBaseline.state = normalizeRecordTimeLabelDomainState(
+        loadedWorkspace.remoteBaseline.state
+      );
+    }
     if (hadLegacyView) {
       const syncMeta = {...loadedWorkspace.syncMeta};
       delete syncMeta.legacyExpandedGroups;
@@ -5017,11 +5140,26 @@ export const createRecordTimeLabelSyncEngine = ({
         failure
       };
     }
+    const remoteState = remote?.state ?? remote?.data;
+    if (remoteState !== undefined && !rtlIsAdmissibleRemoteBaseline(remote)) {
+      const failure = normalizeRecordTimeLabelCloudFailure({
+        class: RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL,
+        code: 'invalid_remote_baseline',
+        reason: 'invalid_remote_baseline',
+        message: 'invalid_remote_baseline'
+      });
+      return {
+        success: false,
+        protocolError: true,
+        reason: 'invalid_remote_baseline',
+        failure,
+        error: toRecordTimeLabelCloudFailureError(failure)
+      };
+    }
     if (remoteRevision <= candidate.remoteBaseline.revision) {
       return {success: true, ignored: true};
     }
     let baselineValue = remoteValue;
-    const remoteState = remote?.state ?? remote?.data;
     const revisionOnlyNotification = !rtlDurableIsObject(remoteState);
     if (remoteRevision > candidate.remoteBaseline.revision + 1 || revisionOnlyNotification) {
       if (typeof cloud?.catchUp !== 'function' && typeof cloud?.bootstrap !== 'function') {
@@ -5044,6 +5182,16 @@ export const createRecordTimeLabelSyncEngine = ({
       if (!(await isCurrent(captured))) return {stale: true, reason: 'stale_session'};
     }
     const applied = applyRemoteBaseline(candidate, baselineValue);
+    if (applied.invalid) {
+      const failure = normalizeRecordTimeLabelCloudFailure({
+        class: RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL,
+        code: 'invalid_remote_baseline',
+        reason: 'invalid_remote_baseline',
+        message: 'invalid_remote_baseline'
+      });
+      return {success: false, protocolError: true, reason: failure.code, failure,
+        error: toRecordTimeLabelCloudFailureError(failure)};
+    }
     if (applied.stale || !applied.changed) return {success: true, ignored: true};
     const reconciledOperations = appendVodSiblingReconciliation(candidate, captured);
     if (!(await persist(candidate, captured))) return {stale: true, reason: 'stale_session'};
@@ -5134,21 +5282,36 @@ export const createRecordTimeLabelSyncEngine = ({
   };
 
   const resetForSessionIdentity = (captured) => {
-    stopCloudSubscription();
+    const retainedOwner = rtlNormalizeUid(captured?.retainedOwnerUid || captured?.ownerUid);
+    const effectiveUid = captured?.localOnly && retainedOwner ? retainedOwner : captured?.uid;
     const sameOwner = Boolean(
       rtlNormalizeUid(workspace.ownerUid) &&
-      rtlNormalizeUid(workspace.ownerUid) === rtlNormalizeUid(captured?.uid)
+      rtlNormalizeUid(workspace.ownerUid) === rtlNormalizeUid(effectiveUid)
     );
+    const incomingEpoch = Number(captured?.workspaceEpoch);
+    const currentEpoch = Number(workspace.workspaceEpoch);
+    // A callback from an older session generation is stale.  Discard it
+    // before touching the active subscription, workspace, or persistence.
+    if (sameOwner && Number.isFinite(incomingEpoch) && Number.isFinite(currentEpoch) && incomingEpoch < currentEpoch) {
+      return {stale: true, reason: 'stale_session'};
+    }
+    stopCloudSubscription();
+    if (captured?.localOnly && sameOwner) {
+      initialized = true;
+      hydrationRequired = false;
+      return {stale: false};
+    }
     const epochIncreased = Number(captured?.workspaceEpoch) > Number(workspace.workspaceEpoch);
     workspace = sameOwner && epochIncreased
       ? rtlRebindSameOwnerWorkspaceEpoch(workspace, captured, now)
       : rtlEmptyDurableWorkspace({
-        ownerUid: captured?.uid,
+        ownerUid: effectiveUid,
         workspaceEpoch: captured?.workspaceEpoch
       });
     initialized = false;
     hydrationRequired = true;
     notify({type: 'session_changed'});
+    return {stale: false};
   };
 
   const startCloudSubscription = (captured, candidate) => {
@@ -5159,7 +5322,7 @@ export const createRecordTimeLabelSyncEngine = ({
       readyState.resolve({success: false, skipped: true, reason: 'hydration_required'});
       return;
     }
-    if (!captured?.uid) {
+    if (!captured?.uid || captured?.localOnly) {
       readyState.resolve({skipped: true, reason: 'anonymous'});
       return;
     }
@@ -5388,7 +5551,14 @@ export const createRecordTimeLabelSyncEngine = ({
         rethrowClassifiedCloudFailure(captured, error);
       }
       if (!(await isCurrent(captured))) return getSnapshot();
-      const applied = applyRemoteBaseline(candidate, bootstrap);
+      const applied = bootstrap?.localOnly === true
+        ? (() => {
+            candidate.localOnly = true;
+            candidate.localState = normalizeRecordTimeLabelDomainState(bootstrap.localState);
+            candidate.remoteBaseline = null;
+            return {changed: true, stale: false};
+          })()
+        : applyRemoteBaseline(candidate, bootstrap);
       if (applied.stale) {
         candidate.syncMeta = {...candidate.syncMeta, hydrationRequired: true};
         if (!(await persist(candidate, captured))) return getSnapshot();
@@ -5437,13 +5607,17 @@ export const createRecordTimeLabelSyncEngine = ({
         enqueue(async () => {
           const current = capture();
           clearAuthTransitionLatchIfSessionChanged(current);
-          const sameIdentity = current.uid === workspace.ownerUid &&
+          const effectiveUid = current.localOnly
+            ? (current.retainedOwnerUid || current.ownerUid || current.uid)
+            : current.uid;
+          const sameIdentity = effectiveUid === workspace.ownerUid &&
             Number(current.workspaceEpoch) === Number(workspace.workspaceEpoch);
           if (sameIdentity) {
             startCloudSubscription(current, workspace);
             return {success: true, tokenRefreshed: true};
           }
-          resetForSessionIdentity(current);
+          const transition = resetForSessionIdentity(current);
+          if (transition?.stale) return transition;
           return {success: true, sessionChanged: true};
         }).catch((error) => {
           logger?.error?.('[RecordTimeLabelCore] durable session callback failed', error);
@@ -5455,14 +5629,23 @@ export const createRecordTimeLabelSyncEngine = ({
   };
 
   const dispatchInternal = async (operations) => {
-    if (!initialized || hydrationRequired) {
-      return {success: false, code: 'recordtimelabel_hydration_required'};
-    }
     const captured = capture();
     clearAuthTransitionLatchIfSessionChanged(captured);
+    // Keep the operation owner live across logout/relogin. A retained,
+    // identity-matching workspace may accept local durable writes while
+    // hydration is pending; cloud sync remains blocked by syncInternal until
+    // the fresh baseline is committed.
+    const retainedWorkspaceAdmission = Boolean(
+      hydrationRequired && workspaceMatchesSession(captured) &&
+      (captured.localOnly === true || captured.allowHydrationDispatch === true)
+    );
+    if ((!initialized || hydrationRequired) && !retainedWorkspaceAdmission) {
+      return {success: false, code: 'recordtimelabel_hydration_required'};
+    }
     if (!(await isCurrent(captured))) return getSnapshot();
     if (!workspaceMatchesSession(captured)) {
-      resetForSessionIdentity(captured);
+      const transition = resetForSessionIdentity(captured);
+      if (transition?.stale) return transition;
       return {success: false, code: 'recordtimelabel_hydration_required'};
     }
     const input = Array.isArray(operations)
@@ -5470,7 +5653,7 @@ export const createRecordTimeLabelSyncEngine = ({
       : (operations && typeof operations === 'object' ? [operations] : []);
     if (input.length === 0) return getSnapshot();
     const candidate = clone(workspace);
-    if (captured?.uid !== undefined && captured?.uid !== null) {
+    if (!captured?.localOnly && captured?.uid !== undefined && captured?.uid !== null) {
       candidate.ownerUid = captured.uid;
     }
     if (captured?.hasEpoch) candidate.workspaceEpoch = captured.workspaceEpoch;
@@ -5478,7 +5661,7 @@ export const createRecordTimeLabelSyncEngine = ({
       client,
       clientId: typeof client === 'string' ? client : client?.id,
       now,
-      ownerUid: captured?.uid ?? candidate.ownerUid,
+      ownerUid: captured?.localOnly ? candidate.ownerUid : (captured?.uid ?? candidate.ownerUid),
       workspaceEpoch: captured?.workspaceEpoch ?? candidate.workspaceEpoch
     }));
     const syncBatchId = rtlStableSyncBatchId(normalized);
@@ -5607,6 +5790,16 @@ export const createRecordTimeLabelSyncEngine = ({
         identityRejectedCount
       };
     }
+    if (captured?.localOnly) {
+      return {
+        success: true,
+        skipped: 'local_only',
+        localOnly: true,
+        pendingCount: workspace.pendingOperations.length,
+        rejectedCount: identityRejectedCount,
+        identityRejectedCount
+      };
+    }
     if (!captured?.uid) {
       return {
         success: true,
@@ -5709,6 +5902,28 @@ export const createRecordTimeLabelSyncEngine = ({
     }
     const responseBaseline = rtlEnvelopePayload(response);
     const responseRevision = responseRevisionInfo.revision;
+    const responseState = responseBaseline?.state ?? responseBaseline?.data;
+    if (responseState !== undefined &&
+      !rtlIsAdmissibleRemoteBaseline({
+        ...responseBaseline,
+        revision: responseRevision
+      })) {
+      const failure = normalizeRecordTimeLabelCloudFailure({
+        class: RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL,
+        code: 'invalid_authoritative_baseline',
+        reason: 'invalid_authoritative_baseline',
+        message: 'invalid_authoritative_baseline'
+      });
+      const error = toRecordTimeLabelCloudFailureError(failure);
+      return persistTerminalFailureBlock({
+        failure,
+        error,
+        captured,
+        timestamp,
+        identityRejectedCount,
+        extra: {protocolError: true}
+      });
+    }
     const parsed = normalizeOperationResults(response, wireOperations);
     if (parsed.error) {
       const failure = normalizeRecordTimeLabelCloudFailure({
@@ -5792,7 +6007,6 @@ export const createRecordTimeLabelSyncEngine = ({
         });
       }
     }
-    const responseState = responseBaseline?.state ?? responseBaseline?.data;
     const responseBaselineForApply = rtlDurableIsObject(responseBaseline) &&
       Number.isSafeInteger(responseRevision)
       ? {...responseBaseline, revision: responseRevision}
@@ -6074,7 +6288,8 @@ export const createRecordTimeLabelSyncEngine = ({
           return getSnapshot();
         }
         if (initialized && !hydrationRequired && !workspaceMatchesSession(captured)) {
-          resetForSessionIdentity(captured);
+          const transition = resetForSessionIdentity(captured);
+          if (transition?.stale) return transition;
         }
         return initialize();
       });
@@ -6741,6 +6956,13 @@ const rtlApplyOperationToPartialDocuments = ({
   };
 };
 
+const rtlHasStaleLifecyclePayload = (payload, ...currentEntities) => {
+  if (!Object.prototype.hasOwnProperty.call(payload || {}, 'lifecycleGeneration')) return false;
+  const incoming = Number(payload.lifecycleGeneration);
+  if (!Number.isSafeInteger(incoming) || incoming < 0) return true;
+  return incoming < rtlMaxLifecycleGeneration(...currentEntities);
+};
+
 const rtlCanRestoreLocalFolder = (root, folder) => {
   if (!folder?.id) return false;
   const tombstones = root?.deletedFolderTombstones;
@@ -6771,6 +6993,13 @@ const rtlEnsureTargetFolder = ({root, folders, localState, folderId, now, allowC
 };
 
 const rtlSetRoot = (target, source) => {
+  // Lifecycle tombstones from the v2 subcollection are merged into the
+  // reducer state for conflict checks, but must never be projected back into
+  // the bounded root document during an ordinary partial rewrite. Preserve
+  // the root-owned (legacy) maps from the current candidate; restore paths
+  // explicitly remove their own legacy entry below when authoritative.
+  const legacyRecordTombstones = clone(target?.deletedRecordTombstones || {});
+  const legacyFolderTombstones = clone(target?.deletedFolderTombstones || {});
   Object.keys(target).forEach((key) => delete target[key]);
   const next = clone(source || {});
   // `Object.assign` invokes the legacy `__proto__` setter on a normal target.
@@ -6785,6 +7014,8 @@ const rtlSetRoot = (target, source) => {
       writable: true
     });
   });
+  target.deletedRecordTombstones = legacyRecordTombstones;
+  target.deletedFolderTombstones = legacyFolderTombstones;
 };
 
 /**
@@ -6908,6 +7139,11 @@ export const planFirestoreV2OperationChanges = ({
           reason = recordId ? 'record_not_found' : 'missing_record_id';
           break;
         }
+        if (rtlHasStaleLifecyclePayload(payload.patch || payload.record,
+          existing, rtlGetLifecycleTombstone(nextDocuments, 'record', recordId))) {
+          reason = 'lifecycle_conflict';
+          break;
+        }
         applied = rtlApplyOperationToPartialDocuments({...nextDocuments, operation, now: operationNow});
         const recordDocument = rtlOwn(applied.documents.records, recordId)
           ? applied.documents.records[recordId]
@@ -6926,6 +7162,11 @@ export const planFirestoreV2OperationChanges = ({
           reason = recordId ? 'record_not_found' : 'missing_record_id';
           break;
         }
+        if (rtlHasStaleLifecyclePayload(payload.record,
+          existing, rtlGetLifecycleTombstone(nextDocuments, 'record', recordId))) {
+          reason = 'lifecycle_conflict';
+          break;
+        }
         const rawTargetFolderId = rtlFirstPresent(payload, ['targetFolderId', 'folderId']);
         if (rawTargetFolderId === undefined || rawTargetFolderId === null) {
           reason = 'missing_target_folder_id';
@@ -7003,6 +7244,10 @@ export const planFirestoreV2OperationChanges = ({
           ? nextDocuments.trash[operationTrashEntryId]
           : null;
         const existingTombstone = rtlGetLifecycleTombstone(nextDocuments, 'record', recordId);
+        if (rtlHasStaleLifecyclePayload(payload.record, existingRecord, existingTombstone)) {
+          reason = 'lifecycle_conflict';
+          break;
+        }
         if (!existingRecord) {
           const hasTrash = Boolean(existingTrashEntry);
           const hasTombstone = Boolean(existingTombstone);
@@ -7119,6 +7364,12 @@ export const planFirestoreV2OperationChanges = ({
             : null);
         if (!targetFolder) { reason = 'folder_not_found'; break; }
         rtlSetRoot(nextDocuments.root, applied.documents.root);
+        // A restore is authoritative for this entity: remove only its
+        // legacy root tombstone. The lifecycle subcollection deletion is
+        // recorded separately below and unrelated legacy entries remain.
+        if (nextDocuments.root.deletedRecordTombstones) {
+          delete nextDocuments.root.deletedRecordTombstones[restoredRecordId];
+        }
         nextDocuments.records[restoredRecordId] = restoredRecord;
         delete nextDocuments.trash[trashEntryId];
         const previousRecordOrder = rtlMergeOrder(targetFolder.recordOrder);
@@ -7157,6 +7408,12 @@ export const planFirestoreV2OperationChanges = ({
           reason = 'folder_not_found';
           break;
         }
+        if (operation.type === OPERATION_TYPES.FOLDER_UPDATE &&
+          rtlHasStaleLifecyclePayload(payload.patch || payload.folder,
+            nextDocuments.folders[folderId], rtlGetLifecycleTombstone(nextDocuments, 'folder', folderId))) {
+          reason = 'lifecycle_conflict';
+          break;
+        }
         const previousOrder = rtlOwn(nextDocuments.folders, folderId)
           ? nextDocuments.folders[folderId]?.recordOrder || []
           : [];

package/src/protocol.js

@@ -20,6 +20,11 @@ export const RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE =
 export const RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE = 'cloud-failure-state-v1';
 export const RECORD_TIMELABEL_CAPABILITY_DETERMINISTIC_PLANNER = 'deterministic-planner-v1';
 export const RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS = 'strict-readiness-v1';
+// Platform adapters use this exact code when their local durable store cannot
+// accept another snapshot. Keep provider-specific matching in the adapter;
+// Core owns only the canonical wire code and recovery semantics.
+export const RECORD_TIMELABEL_CLOUD_FAILURE_CODE_LOCAL_STORAGE_QUOTA_EXCEEDED =
+  'recordtimelabel_local_storage_quota_exceeded';
 // Keep the original capability spelling for rolling compatibility. New
 // clients may advertise the versioned alias while old clients continue to
 // advertise `lifecycle-generation-fence`.
@@ -133,6 +138,8 @@ const CLOUD_FAILURE_CODE_CLASSES = new Map([
   ['too_many_requests', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['network_error', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['network_request_failed', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  [RECORD_TIMELABEL_CLOUD_FAILURE_CODE_LOCAL_STORAGE_QUOTA_EXCEEDED,
+    RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
   ['bootstrap_required', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
   ['bootstraprequired', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
   ['recordtimelabel_bootstrap_required', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
@@ -856,6 +863,7 @@ export const createRecordTimeLabelTransportFailureResults = (
 
 export default {
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CODE_LOCAL_STORAGE_QUOTA_EXCEEDED,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,