@recordtimelabel/core 0.6.1 → 0.6.2

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 published artifact is `0.6.1`:
+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 published artifact is `0.6.2`:
 
 ```json
-"@recordtimelabel/core": "0.6.1"
+"@recordtimelabel/core": "0.6.2"
 ```
 
 If this checkout's `package.json` is ahead of the published version, publish the new package before updating consumers to that version.
@@ -36,6 +36,10 @@ If this checkout's `package.json` is ahead of the published version, publish the
 - `RTL_MAX_SYNC_DRAIN_ROUNDS`
 - `RTL_SYNC_DRAIN_RETRY_DELAY_MS`
 - `RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES`
+- `RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE`
+- `RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES`
+- `normalizeRecordTimeLabelCloudFailure(input)`
+- `toRecordTimeLabelCloudFailureError(input)`
 - `RECORD_TIMELABEL_PROTOCOL_CAPABILITIES`
 - `toRecordTimeLabelWireOperation(operation)`
 - `buildRecordTimeLabelRequestId(namespace, operations)`
@@ -97,6 +101,20 @@ has `load()` and `save(workspace)` methods (adapters may consume the optional se
 `save(workspace, fenceContext)` argument to enforce the session/epoch atomically), and its cloud port has `bootstrap(context, attemptOptions)`,
 `applyOperations(envelope, context)`, and `subscribe(listener, context)` methods. The session port
 provides `current()`, `subscribe(listener)`, and `isCurrent(sessionToken, uid, workspaceEpoch)`.
+`sessionToken` is an opaque fence for equality only. Core never aliases `current.id` or
+the whole session object as an authorization token, and `bootstrap`/`catchUp`/`apply`
+context no longer carries `token`. Platform adapters obtain Firebase credentials from
+their own credential provider.
+
+`normalizeRecordTimeLabelCloudFailure` preserves `status`, `reason`, `retryable`, and
+`retryAfterMs`, and assigns exactly one class: `transient`, `bootstrap-required`,
+`auth-transition-required`, `terminal`, or `stale-session`. Capability
+`cloud-failure-state-v1` advertises this contract. An `auth-transition-required`
+bootstrap or catch-up failure latches that session identity so repeated `init()`
+calls do not invoke `cloud.bootstrap` again. A changed SessionPort capture, UID, or
+workspace epoch clears the latch. `recoverBaseline` falls back from catch-up only for
+explicit `bootstrap-required` / cursor-gap outcomes; auth and transient failures keep
+their class and must not start a second full walk.
 
 The persisted workspace is versioned and contains only durable data:
 

package/package.json

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

package/src/index.js

@@ -1,26 +1,34 @@
 import {
+  RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   buildRecordTimeLabelRequestId,
   createRecordTimeLabelTransportFailureResults,
+  normalizeRecordTimeLabelCloudFailure,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelOperationResults,
+  toRecordTimeLabelCloudFailureError,
   toRecordTimeLabelWireOperation
 } from './protocol.js';
 
 export {
+  RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   buildRecordTimeLabelRequestId,
   createRecordTimeLabelTransportFailureResults,
+  normalizeRecordTimeLabelCloudFailure,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelOperationResults,
+  toRecordTimeLabelCloudFailureError,
   toRecordTimeLabelWireOperation
 } from './protocol.js';
 
@@ -119,7 +127,7 @@ export {
   selectBestMatchingTwitchVod
 };
 
-export const RECORD_TIMELABEL_CORE_VERSION = '0.6.1';
+export const RECORD_TIMELABEL_CORE_VERSION = '0.6.2';
 export const RTL_SYNC_PROTOCOL_VERSION = 2;
 export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'fifo-retry-fence',
@@ -128,7 +136,8 @@ export const RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES = Object.freeze([
   'remote-subscription-readiness',
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
-  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE
 ]);
 export const RTL_MAX_OPERATIONS_PER_REQUEST = 20;
 export const RTL_MAX_SYNC_DRAIN_ROUNDS = 50;
@@ -3354,12 +3363,12 @@ const rtlExtractSession = (session, fallbackEpoch = 0) => {
   } catch {
     current = null;
   }
-  // A session port is intentionally small and adapters use both token and
-  // sessionToken spellings.  Preserve the original token (including objects)
-  // for isCurrent, but never put it in a workspace blob.
-  const token = current && typeof current === 'object'
-    ? (current.sessionToken ?? current.token ?? current.id ?? current)
-    : current;
+  // SessionPort.sessionToken is an opaque fence for equality only. Never treat
+  // current.id or the whole session object as an authorization credential.
+  const sessionToken = current && typeof current === 'object' &&
+    Object.prototype.hasOwnProperty.call(current, 'sessionToken')
+    ? current.sessionToken
+    : null;
   const uid = rtlNormalizeUid(current && typeof current === 'object'
     ? (current.uid ?? current.ownerUid)
     : null);
@@ -3370,8 +3379,7 @@ const rtlExtractSession = (session, fallbackEpoch = 0) => {
   return {
     current,
     hasSession: typeof session?.current === 'function',
-    token,
-    sessionToken: token,
+    sessionToken,
     uid,
     workspaceEpoch: hasEpoch
       ? rtlNormalizeWorkspaceEpoch(rawEpoch, fallbackEpoch)
@@ -3380,9 +3388,16 @@ const rtlExtractSession = (session, fallbackEpoch = 0) => {
   };
 };
 
+const rtlSameSessionIdentity = (left, right) => (
+  Boolean(left) &&
+  Boolean(right) &&
+  left.uid === right.uid &&
+  Number(left.workspaceEpoch) === Number(right.workspaceEpoch) &&
+  Object.is(left.sessionToken, right.sessionToken)
+);
+
 const rtlSessionContext = (captured, workspace, client) => ({
   sessionToken: captured?.sessionToken ?? null,
-  token: captured?.token ?? null,
   uid: captured?.uid ?? (captured?.hasSession ? null : workspace?.ownerUid ?? null),
   ownerUid: captured?.uid ?? (captured?.hasSession ? null : workspace?.ownerUid ?? null),
   workspaceEpoch: workspace?.workspaceEpoch ?? captured?.workspaceEpoch ?? 0,
@@ -3516,6 +3531,7 @@ export const createRecordTimeLabelSyncEngine = ({
     })
   };
   let bootstrapAttemptSequence = 0;
+  let authTransitionLatch = null;
   const listeners = new Set();
   let queue = Promise.resolve();
 
@@ -3568,7 +3584,11 @@ export const createRecordTimeLabelSyncEngine = ({
     }
     if (typeof session?.current !== 'function') return true;
     const current = rtlExtractSession(session, captured.workspaceEpoch);
-    if (captured.token !== undefined && captured.token !== null && current.token !== captured.token) return false;
+    if (
+      captured.sessionToken !== undefined &&
+      captured.sessionToken !== null &&
+      !Object.is(current.sessionToken, captured.sessionToken)
+    ) return false;
     if (captured.uid !== current.uid) return false;
     return !captured.hasEpoch || current.workspaceEpoch === captured.workspaceEpoch;
   };
@@ -3618,21 +3638,75 @@ export const createRecordTimeLabelSyncEngine = ({
 
   const normalizeBootstrapResponse = (response) => {
     if (!rtlEnvelopeSuccess(response)) {
-      const error = new Error(response?.error?.message || response?.message || 'recordtimelabel_bootstrap_failed');
-      error.code = response?.error?.code || response?.code || 'recordtimelabel_bootstrap_failed';
-      throw error;
+      throw toRecordTimeLabelCloudFailureError({
+        ...((response && typeof response === 'object') ? response : {}),
+        message: response?.error?.message || response?.message || 'recordtimelabel_bootstrap_failed',
+        code: response?.error?.code || response?.code || 'recordtimelabel_bootstrap_failed',
+        reason: response?.error?.reason || response?.reason ||
+          response?.error?.code || response?.code || 'recordtimelabel_bootstrap_failed'
+      });
     }
     const remote = rtlEnvelopePayload(response);
     const revision = Number(remote?.revision);
     const state = remote?.state ?? remote?.data;
     if (!remote || !rtlDurableIsObject(state) || !Number.isFinite(revision) || revision < 0) {
-      const error = new Error('recordtimelabel_invalid_bootstrap_response');
-      error.code = 'recordtimelabel_invalid_bootstrap_response';
-      throw error;
+      throw toRecordTimeLabelCloudFailureError({
+        code: 'recordtimelabel_invalid_bootstrap_response',
+        reason: 'recordtimelabel_invalid_bootstrap_response',
+        message: 'recordtimelabel_invalid_bootstrap_response',
+        retryable: false
+      });
     }
     return {state, revision, changeCursor: remote.changeCursor ?? null};
   };
 
+  const clearAuthTransitionLatchIfSessionChanged = (captured) => {
+    if (!authTransitionLatch) return;
+    if (!rtlSameSessionIdentity(authTransitionLatch, captured)) {
+      authTransitionLatch = null;
+    }
+  };
+
+  const throwIfAuthTransitionLatched = (captured) => {
+    clearAuthTransitionLatchIfSessionChanged(captured);
+    if (!authTransitionLatch) return;
+    throw toRecordTimeLabelCloudFailureError(authTransitionLatch.failure);
+  };
+
+  const rememberAuthTransitionFailure = (captured, failure) => {
+    if (failure?.class !== RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED) {
+      return;
+    }
+    authTransitionLatch = {
+      uid: captured?.uid ?? null,
+      sessionToken: captured?.sessionToken ?? null,
+      workspaceEpoch: captured?.workspaceEpoch ?? 0,
+      failure: {
+        class: failure.class,
+        status: failure.status ?? null,
+        reason: failure.reason ?? failure.code ?? 'auth-transition-required',
+        code: failure.code ?? failure.reason ?? 'auth-transition-required',
+        message: failure.message || failure.reason || failure.code || 'auth-transition-required',
+        retryable: false,
+        retryAfterMs: null,
+        bootstrapRequired: false
+      }
+    };
+  };
+
+  const capturedFromContext = (context) => ({
+    uid: context?.uid ?? null,
+    sessionToken: context?.sessionToken ?? null,
+    workspaceEpoch: context?.workspaceEpoch ?? 0
+  });
+
+  const rethrowClassifiedCloudFailure = (captured, error) => {
+    const failure = normalizeRecordTimeLabelCloudFailure(error);
+    rememberAuthTransitionFailure(captured, failure);
+    if (error?.class === failure.class) throw error;
+    throw toRecordTimeLabelCloudFailureError(failure);
+  };
+
   const requireBootstrapRevision = (baseline, minimumRevision) => {
     const minimum = Number(minimumRevision);
     if (Number.isFinite(minimum) && Number(baseline?.revision) < minimum) {
@@ -3651,10 +3725,13 @@ 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 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.
+  // bootstrap walk only for explicit bootstrap-required / cursor-gap
+  // outcomes. Auth and transient failures keep their class and must not
+  // start a second full walk. A successful but stale catch-up response is
+  // fail-closed: falling back would hide a revision contract violation.
   const recoverBaseline = async (context, targetRevision, mode) => {
+    const captured = capturedFromContext(context);
+    throwIfAuthTransitionLatched(captured);
     if (typeof cloud?.catchUp === 'function') {
       try {
         const caught = await cloud.catchUp(context, {
@@ -3665,20 +3742,35 @@ export const createRecordTimeLabelSyncEngine = ({
         if (rtlEnvelopeSuccess(caught)) {
           return requireBootstrapRevision(normalizeBootstrapResponse(caught), targetRevision);
         }
+        const failure = normalizeRecordTimeLabelCloudFailure(caught);
+        if (failure.class !== RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED) {
+          rethrowClassifiedCloudFailure(captured, failure);
+        }
       } catch (error) {
         if (error?.code === 'recordtimelabel_bootstrap_revision_behind_required') {
           throw error;
         }
-        logger?.warn?.('[RecordTimeLabelCore] catch-up failed, falling back to bootstrap', error);
+        if (error?.class === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED ||
+            normalizeRecordTimeLabelCloudFailure(error).class ===
+              RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED) {
+          // Explicit gap recovery only.
+        } else {
+          rethrowClassifiedCloudFailure(captured, error);
+        }
       }
     }
-    return requireBootstrapRevision(
-      normalizeBootstrapResponse(await cloud.bootstrap(
-        context,
-        bootstrapAttemptOptions(mode)
-      )),
-      targetRevision
-    );
+    throwIfAuthTransitionLatched(captured);
+    try {
+      return requireBootstrapRevision(
+        normalizeBootstrapResponse(await cloud.bootstrap(
+          context,
+          bootstrapAttemptOptions(mode)
+        )),
+        targetRevision
+      );
+    } catch (error) {
+      rethrowClassifiedCloudFailure(captured, error);
+    }
   };
 
   const normalizeLoadedWorkspace = (loaded, captured) => {
@@ -4012,6 +4104,7 @@ export const createRecordTimeLabelSyncEngine = ({
 
   const initialize = async () => {
     const captured = capture();
+    throwIfAuthTransitionLatched(captured);
     const loaded = await storage.load();
     if (!(await isCurrent(captured))) return getSnapshot();
     // Read the raw owner and baseline before normalizeLoadedWorkspace adopts
@@ -4050,7 +4143,7 @@ export const createRecordTimeLabelSyncEngine = ({
         ));
       } catch (error) {
         if (!(await isCurrent(captured))) return getSnapshot();
-        throw error;
+        rethrowClassifiedCloudFailure(captured, error);
       }
       if (!(await isCurrent(captured))) return getSnapshot();
       applyRemoteBaseline(candidate, bootstrap);
@@ -4068,6 +4161,7 @@ export const createRecordTimeLabelSyncEngine = ({
         if (destroyed) return;
         enqueue(async () => {
           const current = capture();
+          clearAuthTransitionLatchIfSessionChanged(current);
           const sameIdentity = current.uid === workspace.ownerUid &&
             Number(current.workspaceEpoch) === Number(workspace.workspaceEpoch);
           if (sameIdentity) {
@@ -4420,7 +4514,7 @@ export const createRecordTimeLabelSyncEngine = ({
         );
       } catch (error) {
         if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
-        throw error;
+        rethrowClassifiedCloudFailure(captured, error);
       }
       if (!(await isCurrent(captured))) return {success: false, reason: 'stale_session'};
       applyRemoteBaseline(candidate, freshBaseline);
@@ -5664,9 +5758,13 @@ export default {
   isPendingChannelFolderId,
   isValidChannelName,
   RECORD_TIMELABEL_DURABLE_ENGINE_CAPABILITIES,
+  RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
+  normalizeRecordTimeLabelCloudFailure,
+  toRecordTimeLabelCloudFailureError,
   RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   RTL_SYNC_PROTOCOL_VERSION,

package/src/protocol.js

@@ -23,6 +23,237 @@ export const RECORD_TIMELABEL_PROTOCOL_CAPABILITIES = Object.freeze([
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE
 ]);
 
+export const RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES = Object.freeze({
+  TRANSIENT: 'transient',
+  BOOTSTRAP_REQUIRED: 'bootstrap-required',
+  AUTH_TRANSITION_REQUIRED: 'auth-transition-required',
+  TERMINAL: 'terminal',
+  STALE_SESSION: 'stale-session'
+});
+
+export const RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE = 'cloud-failure-state-v1';
+
+const CLOUD_FAILURE_CLASS_VALUES = new Set(Object.values(RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES));
+
+const AUTH_TRANSITION_CODES = new Set([
+  'auth-transition-required',
+  'auth_transition_required',
+  'malformed_id_token',
+  'invalid_id_token',
+  'unauthenticated',
+  'expired_id_token',
+  'id_token_expired',
+  'token_expired',
+  'token_project_mismatch',
+  'token_user_mismatch',
+  'token_not_yet_valid',
+  'missing_token',
+  'missing_uid',
+  'token_refresh_failed',
+  'token_refresh_required'
+]);
+
+const BOOTSTRAP_REQUIRED_CODES = new Set([
+  'bootstrap-required',
+  'bootstrap_required',
+  'bootstraprequired',
+  'expired_bootstrap_cursor',
+  'invalid_bootstrap_cursor',
+  'revision_gap',
+  'recordtimelabel_bootstrap_required'
+]);
+
+const STALE_SESSION_CODES = new Set([
+  'stale-session',
+  'stale_session',
+  'recordtimelabel_stale_session',
+  'auth_context_changed'
+]);
+
+const TERMINAL_CONFLICT_CODES = new Set([
+  'operation_id_conflict',
+  'operation_request_invalid_ids',
+  'operation_result_count_mismatch',
+  'operation_result_incomplete',
+  'operation_result_duplicate_id',
+  'operation_result_unknown_id',
+  'operation_result_missing_id',
+  'operation_result_ambiguous_id'
+]);
+
+const pickFailureText = (...values) => {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+};
+
+const unwrapFailureSource = (input) => {
+  if (input == null) return {};
+  if (typeof input === 'string') return {message: input, reason: input, code: input};
+  if (typeof input !== 'object') return {message: String(input)};
+  const nested = input.error && typeof input.error === 'object' ? input.error : null;
+  return nested ? {...nested, ...input, error: nested} : input;
+};
+
+const normalizeFailureClass = (value) => (
+  CLOUD_FAILURE_CLASS_VALUES.has(value) ? value : null
+);
+
+const normalizeFailureRetryAfterMs = (value) => {
+  if (value === null || value === undefined || value === '') return null;
+  const retryAfterMs = Number(value);
+  return Number.isFinite(retryAfterMs) && retryAfterMs >= 0 ? retryAfterMs : null;
+};
+
+const collectFailureTokens = (source) => [
+  source.class,
+  source.failureClass,
+  source.cloudFailureClass,
+  source.code,
+  source.reason,
+  source.name,
+  source.message,
+  source.error,
+  source.error?.code,
+  source.error?.reason,
+  source.error?.message,
+  source.error?.name
+].flatMap((value) => {
+  if (typeof value !== 'string') return [];
+  return value.toLowerCase().split(/[^a-z0-9_-]+/).filter(Boolean);
+});
+
+const looksLikeNetworkFailure = (source, tokens) => {
+  const blob = [
+    source.name,
+    source.code,
+    source.reason,
+    source.message,
+    source.error?.name,
+    source.error?.code,
+    source.error?.reason,
+    source.error?.message
+  ].filter(Boolean).join(' ').toLowerCase();
+  return Boolean(
+    tokens.includes('retryable') ||
+    tokens.includes('unavailable') ||
+    tokens.includes('temporarily_unavailable') ||
+    tokens.includes('bulk_job_in_progress') ||
+    tokens.includes('deadline_exceeded') ||
+    tokens.includes('network_error') ||
+    tokens.includes('err_network') ||
+    tokens.includes('econnreset') ||
+    tokens.includes('etimedout') ||
+    blob.includes('failed to fetch') ||
+    blob.includes('fetch failed') ||
+    blob.includes('network-request-failed') ||
+    blob.includes('network request failed')
+  );
+};
+
+const classifyRecordTimeLabelCloudFailure = (source, status, tokens) => {
+  const explicitClass = normalizeFailureClass(
+    source.class ?? source.failureClass ?? source.cloudFailureClass
+  );
+  if (explicitClass) return explicitClass;
+  if (
+    source.stale === true ||
+    tokens.some((token) => STALE_SESSION_CODES.has(token) || token === 'stale-session')
+  ) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION;
+  }
+  if (
+    status === 401 ||
+    tokens.some((token) => AUTH_TRANSITION_CODES.has(token))
+  ) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED;
+  }
+  if (
+    source.bootstrapRequired === true ||
+    source.bootstrap_required === true ||
+    tokens.some((token) => BOOTSTRAP_REQUIRED_CODES.has(token))
+  ) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED;
+  }
+  if (tokens.some((token) => TERMINAL_CONFLICT_CODES.has(token))) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL;
+  }
+  const retryable = source.retryable === true || source.error?.retryable === true;
+  if (
+    status === 408 ||
+    status === 425 ||
+    status === 429 ||
+    status === 409 ||
+    (Number.isFinite(status) && status >= 500) ||
+    retryable ||
+    looksLikeNetworkFailure(source, tokens)
+  ) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT;
+  }
+  return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL;
+};
+
+/**
+ * Classify a cloud/bootstrap/catch-up failure without inspecting JWT structure
+ * or Firebase SDKs. Adapters may pass Firebase codes as opaque reason/code
+ * strings; this helper only preserves metadata and assigns one class.
+ */
+export const normalizeRecordTimeLabelCloudFailure = (input = {}) => {
+  const source = unwrapFailureSource(input);
+  const statusValue = Number(source.status ?? source.statusCode ?? source.error?.status);
+  const status = Number.isFinite(statusValue) ? statusValue : null;
+  const tokens = collectFailureTokens(source);
+  const failureClass = classifyRecordTimeLabelCloudFailure(source, status, tokens);
+  const reason = pickFailureText(
+    source.reason,
+    source.error?.reason,
+    source.code,
+    source.error?.code,
+    source.message,
+    source.error?.message
+  );
+  const code = pickFailureText(
+    source.code,
+    source.error?.code,
+    reason,
+    'recordtimelabel_cloud_failure'
+  );
+  const message = pickFailureText(
+    source.message,
+    source.error?.message,
+    reason,
+    code,
+    'recordtimelabel_cloud_failure'
+  );
+  const retryAfterMs = failureClass === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT
+    ? normalizeFailureRetryAfterMs(source.retryAfterMs ?? source.error?.retryAfterMs)
+    : null;
+  return {
+    class: failureClass,
+    status,
+    reason,
+    code,
+    message,
+    retryable: failureClass === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT,
+    retryAfterMs,
+    bootstrapRequired: failureClass === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED
+  };
+};
+
+export const toRecordTimeLabelCloudFailureError = (input = {}) => {
+  const failure = normalizeRecordTimeLabelCloudFailure(input);
+  const error = new Error(failure.message);
+  error.class = failure.class;
+  error.code = failure.code;
+  error.reason = failure.reason;
+  error.status = failure.status;
+  error.retryable = failure.retryable;
+  error.retryAfterMs = failure.retryAfterMs;
+  error.bootstrapRequired = failure.bootstrapRequired;
+  return error;
+};
+
 const ALLOWED_OPERATION_RESULT_STATUSES = new Set(
   Object.values(RECORD_TIMELABEL_OPERATION_RESULT_STATUSES)
 );
@@ -269,10 +500,14 @@ export default {
   RECORD_TIMELABEL_CAPABILITY_OPERATION_CONFLICT_QUARANTINE,
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
+  RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE,
+  RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   toRecordTimeLabelWireOperation,
   buildRecordTimeLabelRequestId,
   createRecordTimeLabelTransportFailureResults,
   normalizeRecordTimeLabelOperationResults,
-  normalizeRecordTimeLabelEnvelopeResponse
+  normalizeRecordTimeLabelEnvelopeResponse,
+  normalizeRecordTimeLabelCloudFailure,
+  toRecordTimeLabelCloudFailureError
 };