@recordtimelabel/core 0.6.2 → 0.6.5

package/src/protocol.js

@@ -17,12 +17,54 @@ export const RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS =
   'strict-operation-results';
 export const RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE =
   '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';
+// Keep the original capability spelling for rolling compatibility. New
+// clients may advertise the versioned alias while old clients continue to
+// advertise `lifecycle-generation-fence`.
+export const RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE_V1 =
+  'lifecycle-generation-fence-v1';
+export const RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION = 1;
 export const RECORD_TIMELABEL_PROTOCOL_CAPABILITIES = Object.freeze([
   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,
+  RECORD_TIMELABEL_CAPABILITY_DETERMINISTIC_PLANNER,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE_V1
 ]);
 
+const IMMUTABLE_ID_MAX_BYTES = 512;
+const IMMUTABLE_ID_MAX_CODEPOINTS = 512;
+const immutableId = (value) => {
+  if (typeof value !== 'string' || value.length === 0 || value !== value.trim() ||
+    value !== value.normalize('NFC') ||
+    value === '.' || value === '..' || value === '__proto__' || value === 'prototype' || value === 'constructor' ||
+    value.includes('/') || value.includes('\\') ||
+    /[\u0000-\u001F\u007F-\u009F]/u.test(value) ||
+    /\p{Cf}/u.test(value) ||
+    Array.from(value).length > IMMUTABLE_ID_MAX_CODEPOINTS ||
+    (() => {
+      for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xD800 && code <= 0xDBFF) {
+          const next = value.charCodeAt(index + 1);
+          if (!(next >= 0xDC00 && next <= 0xDFFF)) return true;
+          index += 1;
+        } else if (code >= 0xDC00 && code <= 0xDFFF) return true;
+      }
+      return false;
+    })() || new TextEncoder().encode(value).byteLength > IMMUTABLE_ID_MAX_BYTES) {
+    return null;
+  }
+  return value;
+};
+
+export const normalizeRecordTimeLabelImmutableId = immutableId;
+export const normalizeRecordTimeLabelPlannerId = immutableId;
+
 export const RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES = Object.freeze({
   TRANSIENT: 'transient',
   BOOTSTRAP_REQUIRED: 'bootstrap-required',
@@ -31,54 +73,106 @@ export const RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES = Object.freeze({
   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'
+// Keep operation-conflict aliases in one wire-compatibility table.  The
+// durable engine consumes the exported predicate below instead of maintaining
+// a second, subtly different list of aliases.
+const OPERATION_CONFLICT_CODES = new Set([
+  'operation_id_conflict',
+  'operationidconflict',
+  'operation_conflict',
+  'operation_conflict_id',
+  'operation_request_id_conflict',
+  'operation_request_conflict',
+  'operation_request_hash_conflict',
+  'operation_id_hash_conflict',
+  'operation_id_payload_conflict',
+  'operation_id_content_mismatch',
+  'operation_payload_conflict',
+  'duplicate_operation_id',
+  'duplicate_request_id',
+  'request_id_conflict',
+  'request_id_content_mismatch',
+  'request_id_hash_conflict',
+  'request_id_payload_mismatch',
+  'request_hash_conflict',
+  'request_hash_mismatch',
+  'idempotency_conflict',
+  'idempotency_key_conflict',
+  'idempotency_key_mismatch',
+  'recordtimelabel_operation_id_conflict'
 ]);
 
-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'
+// These aliases are part of the wire compatibility surface.  Keep the
+// matching deliberately exact after canonicalisation: an arbitrary provider
+// error message must not override an explicit HTTP/status heuristic, while a
+// gateway's well-known code must.
+const CLOUD_FAILURE_CODE_CLASSES = new Map([
+  ['transient', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['retryable', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['temporary', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['temporarily_unavailable', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['unavailable', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['deadline_exceeded', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT],
+  ['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],
+  ['network_request_failed', 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],
+  ['expired_bootstrap_cursor', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
+  ['invalid_bootstrap_cursor', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
+  ['revision_gap', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED],
+  ['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],
+  ['stale_uid', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
+  ['stale_epoch', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
+  ['uid_mismatch', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
+  ['workspace_epoch_mismatch', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION],
+  ['auth_transition_required', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  ['auth_invalid', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  ['auth_revoked', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  ['auth_disabled', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  ['invalid_id_token', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  ['unauthenticated', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  ['permission_denied', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.AUTH_TRANSITION_REQUIRED],
+  // The wire class is also accepted in `code` for adapters that flatten a
+  // canonical failure.  Keep this explicit rather than falling back to the
+  // HTTP status heuristic (a flattened terminal 409 must not become retryable).
+  ['terminal', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['validation_failed', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['invalid_operation', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['invalid_operation_batch', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['malformed_operation', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['operation_rejected', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['protocol_error', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['operation_result_count_mismatch', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['lifecycle_conflict', RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL],
+  ['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
+  ])
 ]);
 
 const pickFailureText = (...values) => {
@@ -88,17 +182,140 @@ const pickFailureText = (...values) => {
   return null;
 };
 
+const canonicalizeFailureCode = (value) => {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim().toLowerCase()
+    .replace(/[/:.\-\s]+/g, '_');
+  return normalized || null;
+};
+
+const failureCodeClass = (value) => {
+  const normalized = canonicalizeFailureCode(value);
+  return normalized ? CLOUD_FAILURE_CODE_CLASSES.get(normalized) || null : null;
+};
+
+const asFailureObject = (value) => (
+  value && typeof value === 'object' && !Array.isArray(value) ? value : 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 canonicalFailure = asFailureObject(input.failure);
+  const legacyError = asFailureObject(input.error);
+  const canonicalString = typeof input.failure === 'string' && input.failure.trim()
+    ? input.failure.trim()
+    : '';
+  const legacyString = typeof input.error === 'string' && input.error.trim()
+    ? input.error.trim()
+    : '';
+  if (!canonicalFailure && !legacyError && !canonicalString && !legacyString) return input;
+  const canonicalMarker = canonicalString || null;
+  const legacyMarker = legacyString || null;
+  const canonicalValue = canonicalFailure || (canonicalMarker ? {
+    message: canonicalMarker,
+    reason: canonicalMarker,
+    code: canonicalMarker
+  } : null);
+  const legacyValue = legacyError || (legacyMarker ? {
+    message: legacyMarker,
+    reason: legacyMarker,
+    code: legacyMarker
+  } : null);
+  // A canonical `failure` object is authoritative when an adapter also
+  // leaves legacy fields at the envelope level.  Otherwise retain the old
+  // `error` object compatibility path.
+  return {
+    ...(legacyValue || {}),
+    ...input,
+    ...(legacyError ? {error: legacyError} : {}),
+    ...(canonicalValue || {}),
+    ...(canonicalFailure ? {failure: canonicalFailure} : {}),
+    reason: canonicalValue
+      ? pickFailureText(
+        canonicalValue.reason,
+        canonicalValue.error?.reason,
+        canonicalValue.code,
+        canonicalValue.error?.code,
+        legacyValue?.reason,
+        legacyValue?.error?.reason,
+        input.reason,
+        canonicalValue.error,
+        legacyValue?.error,
+        canonicalMarker,
+        legacyMarker
+      )
+      : pickFailureText(
+        input.reason,
+        legacyValue?.reason,
+        legacyValue?.error?.reason,
+        legacyValue?.error,
+        legacyMarker
+      ),
+    code: canonicalValue
+      ? pickFailureText(
+        canonicalValue.code,
+        canonicalValue.error?.code,
+        legacyValue?.code,
+        legacyValue?.error?.code,
+        input.code,
+        typeof canonicalValue.error === 'string' ? canonicalValue.error : null,
+        typeof legacyValue?.error === 'string' ? legacyValue.error : null,
+        canonicalMarker,
+        legacyMarker
+      )
+      : pickFailureText(
+        input.code,
+        legacyValue?.code,
+        typeof legacyValue?.error === 'string' ? legacyValue.error : null,
+        legacyMarker
+      ),
+    message: canonicalValue
+      ? pickFailureText(
+        canonicalValue.message,
+        canonicalValue.error?.message,
+        canonicalValue.reason,
+        canonicalValue.code,
+        legacyValue?.message,
+        legacyValue?.error?.message,
+        input.message,
+        typeof canonicalValue.error === 'string' ? canonicalValue.error : null,
+        typeof legacyValue?.error === 'string' ? legacyValue.error : null,
+        canonicalMarker,
+        legacyMarker
+      )
+      : pickFailureText(
+        input.message,
+        legacyValue?.message,
+        typeof legacyValue?.error === 'string' ? legacyValue.error : null,
+        legacyMarker
+      ),
+    // Keep the original nested objects available to the classifier so that a
+    // canonical value can win over a conflicting outer status/code.
+    __canonicalFailure: canonicalFailure,
+    __canonicalFailureMarker: canonicalMarker,
+    __legacyError: legacyError,
+    __legacyFailureMarker: legacyMarker,
+    __outerFailureEnvelope: input
+  };
 };
 
-const normalizeFailureClass = (value) => (
-  CLOUD_FAILURE_CLASS_VALUES.has(value) ? value : null
-);
+const normalizeFailureClass = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (CLOUD_FAILURE_CLASS_VALUES.has(trimmed)) return trimmed;
+  const kebab = trimmed.toLowerCase().replace(/_/g, '-');
+  return CLOUD_FAILURE_CLASS_VALUES.has(kebab) ? kebab : null;
+};
+
+const explicitFailureClass = (...values) => values
+  .map((value) => normalizeFailureClass(value))
+  .find(Boolean);
+
+const knownFailureCodeClass = (...values) => values
+  .map((value) => failureCodeClass(value))
+  .find(Boolean);
 
 const normalizeFailureRetryAfterMs = (value) => {
   if (value === null || value === undefined || value === '') return null;
@@ -106,25 +323,7 @@ const normalizeFailureRetryAfterMs = (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 looksLikeNetworkFailure = (source) => {
   const blob = [
     source.name,
     source.code,
@@ -136,49 +335,97 @@ const looksLikeNetworkFailure = (source, tokens) => {
     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')
+    blob.includes('network request failed') ||
+    blob.includes('network_error') ||
+    blob.includes('err_network') ||
+    blob.includes('econnreset') ||
+    blob.includes('etimedout')
   );
 };
 
-const classifyRecordTimeLabelCloudFailure = (source, status, tokens) => {
-  const explicitClass = normalizeFailureClass(
-    source.class ?? source.failureClass ?? source.cloudFailureClass
+const classifyRecordTimeLabelCloudFailure = (source, status) => {
+  const canonical = source.__canonicalFailure;
+  const canonicalMarker = source.__canonicalFailureMarker;
+  const legacy = source.__legacyError;
+  const legacyMarker = source.__legacyFailureMarker;
+  const outer = source.__outerFailureEnvelope || source;
+
+  // A canonical nested class is the strongest signal.  A canonical code (or
+  // string marker) is next, before any compatibility field at the envelope
+  // level.  This preserves canonical operation conflicts even when an older
+  // gateway leaves a contradictory retryable class beside `failure`.
+  const canonicalExplicitClass = explicitFailureClass(
+    canonical?.class,
+    canonical?.failureClass,
+    canonical?.cloudFailureClass
   );
-  if (explicitClass) return explicitClass;
-  if (
-    source.stale === true ||
-    tokens.some((token) => STALE_SESSION_CODES.has(token) || token === 'stale-session')
-  ) {
+  if (canonicalExplicitClass) return canonicalExplicitClass;
+  const canonicalCodeClass = knownFailureCodeClass(
+    canonical?.code,
+    canonical?.reason,
+    canonical?.error?.code,
+    canonical?.error?.reason,
+    canonical?.message,
+    canonical?.error?.message,
+    canonical?.error,
+    canonicalMarker
+  );
+  if (canonicalCodeClass) return canonicalCodeClass;
+
+  // These canonical boolean markers are class-bearing wire fields too.  Keep
+  // them ahead of compatibility fields and HTTP heuristics, just like a
+  // canonical class/code.
+  if (canonical?.stale === true) {
     return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION;
   }
-  if (
-    status === 401 ||
-    tokens.some((token) => AUTH_TRANSITION_CODES.has(token))
-  ) {
+  if (canonical?.bootstrapRequired === true || canonical?.bootstrap_required === true) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED;
+  }
+
+  const outerExplicitClass = explicitFailureClass(
+    outer.class,
+    outer.failureClass,
+    outer.cloudFailureClass
+  );
+  const legacyExplicitClass = explicitFailureClass(
+    legacy?.class,
+    legacy?.failureClass,
+    legacy?.cloudFailureClass
+  );
+  if (outerExplicitClass || legacyExplicitClass) {
+    return outerExplicitClass || legacyExplicitClass;
+  }
+
+  const legacyCodeClass = knownFailureCodeClass(
+    outer.code,
+    outer.reason,
+    outer.message,
+    outer.error?.code,
+    outer.error?.reason,
+    outer.error?.message,
+    legacy?.code,
+    legacy?.reason,
+    legacy?.message,
+    legacy?.error?.code,
+    legacy?.error?.reason,
+    legacy?.error?.message,
+    legacy?.error,
+    legacyMarker
+  );
+  if (legacyCodeClass) return legacyCodeClass;
+
+  if (source.stale === true) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.STALE_SESSION;
+  }
+  if (status === 401) {
     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))
-  ) {
+  if (source.bootstrapRequired === true || source.bootstrap_required === true) {
     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 ||
@@ -187,13 +434,66 @@ const classifyRecordTimeLabelCloudFailure = (source, status, tokens) => {
     status === 409 ||
     (Number.isFinite(status) && status >= 500) ||
     retryable ||
-    looksLikeNetworkFailure(source, tokens)
+    looksLikeNetworkFailure(source)
   ) {
     return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT;
   }
   return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL;
 };
 
+export const isRecordTimeLabelOperationConflictFailure = (input = {}) => {
+  const source = unwrapFailureSource(input);
+  const failure = normalizeRecordTimeLabelCloudFailure(input);
+  if (failure.class !== RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL) return false;
+  const canonical = source.__canonicalFailure;
+  const canonicalMarker = source.__canonicalFailureMarker;
+  const canonicalClassDecided = Boolean(
+    explicitFailureClass(
+      canonical?.class,
+      canonical?.failureClass,
+      canonical?.cloudFailureClass
+    ) ||
+    knownFailureCodeClass(
+      canonical?.code,
+      canonical?.reason,
+      canonical?.error?.code,
+      canonical?.error?.reason,
+      canonical?.message,
+      canonical?.error?.message,
+      canonical?.error,
+      canonicalMarker
+    ) ||
+    canonical?.stale === true ||
+    canonical?.bootstrapRequired === true ||
+    canonical?.bootstrap_required === true
+  );
+  // Keep conflict detection in the same precedence layer as classification:
+  // once canonical failure metadata selected the terminal class, legacy and
+  // outer compatibility fields must not turn a generic terminal into a
+  // quarantine-eligible operation conflict.
+  const values = canonicalClassDecided
+    ? [
+      canonical?.code,
+      canonical?.reason,
+      canonical?.error?.code,
+      canonical?.error?.reason,
+      canonicalMarker
+    ]
+    : [
+      source.__legacyError?.code,
+      source.__legacyError?.reason,
+      source.__legacyFailureMarker,
+      source.__outerFailureEnvelope?.code,
+      source.__outerFailureEnvelope?.reason,
+      source.__outerFailureEnvelope?.error?.code,
+      source.__outerFailureEnvelope?.error?.reason
+    ];
+  return values.some((value) => {
+    const normalized = canonicalizeFailureCode(value);
+    return normalized ? OPERATION_CONFLICT_CODES.has(normalized) : false;
+  });
+};
+
 /**
  * Classify a cloud/bootstrap/catch-up failure without inspecting JWT structure
  * or Firebase SDKs. Adapters may pass Firebase codes as opaque reason/code
@@ -201,10 +501,17 @@ const classifyRecordTimeLabelCloudFailure = (source, status, tokens) => {
  */
 export const normalizeRecordTimeLabelCloudFailure = (input = {}) => {
   const source = unwrapFailureSource(input);
-  const statusValue = Number(source.status ?? source.statusCode ?? source.error?.status);
+  const statusValue = Number(
+    source.__canonicalFailure?.status ??
+    source.__canonicalFailure?.statusCode ??
+    source.__legacyError?.status ??
+    source.__legacyError?.statusCode ??
+    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 failureClass = classifyRecordTimeLabelCloudFailure(source, status);
   const reason = pickFailureText(
     source.reason,
     source.error?.reason,
@@ -229,8 +536,20 @@ export const normalizeRecordTimeLabelCloudFailure = (input = {}) => {
   const retryAfterMs = failureClass === RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TRANSIENT
     ? normalizeFailureRetryAfterMs(source.retryAfterMs ?? source.error?.retryAfterMs)
     : null;
+  const rawSchemaVersion = source.__canonicalFailure?.schemaVersion ??
+    source.schemaVersion;
+  const schemaVersion = Number(rawSchemaVersion);
+  const requestId = pickFailureText(
+    source.__canonicalFailure?.requestId,
+    source.requestId,
+    source.error?.requestId
+  );
   return {
+    schemaVersion: Number.isSafeInteger(schemaVersion) && schemaVersion > 0
+      ? schemaVersion
+      : RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
     class: failureClass,
+    requestId,
     status,
     reason,
     code,
@@ -244,6 +563,7 @@ export const normalizeRecordTimeLabelCloudFailure = (input = {}) => {
 export const toRecordTimeLabelCloudFailureError = (input = {}) => {
   const failure = normalizeRecordTimeLabelCloudFailure(input);
   const error = new Error(failure.message);
+  error.schemaVersion = failure.schemaVersion;
   error.class = failure.class;
   error.code = failure.code;
   error.reason = failure.reason;
@@ -251,6 +571,12 @@ export const toRecordTimeLabelCloudFailureError = (input = {}) => {
   error.retryable = failure.retryable;
   error.retryAfterMs = failure.retryAfterMs;
   error.bootstrapRequired = failure.bootstrapRequired;
+  error.requestId = failure.requestId;
+  Object.defineProperty(error, 'failure', {
+    value: failure,
+    enumerable: false,
+    configurable: true
+  });
   return error;
 };
 
@@ -367,6 +693,7 @@ const isSuccessfulEnvelope = (response) => {
     response.success === false ||
     response.ok === false ||
     response.error ||
+    response.failure ||
     response.code === 'error'
   ) return false;
   return response.success === true || response.ok === true || (
@@ -501,6 +828,10 @@ export default {
   RECORD_TIMELABEL_CAPABILITY_STRICT_OPERATION_RESULTS,
   RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE,
   RECORD_TIMELABEL_CAPABILITY_CLOUD_FAILURE_STATE,
+  RECORD_TIMELABEL_CAPABILITY_DETERMINISTIC_PLANNER,
+  RECORD_TIMELABEL_CAPABILITY_STRICT_READINESS,
+  RECORD_TIMELABEL_CAPABILITY_LIFECYCLE_GENERATION_FENCE_V1,
+  RECORD_TIMELABEL_CLOUD_FAILURE_SCHEMA_VERSION,
   RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES,
   RECORD_TIMELABEL_PROTOCOL_CAPABILITIES,
   toRecordTimeLabelWireOperation,
@@ -509,5 +840,8 @@ export default {
   normalizeRecordTimeLabelOperationResults,
   normalizeRecordTimeLabelEnvelopeResponse,
   normalizeRecordTimeLabelCloudFailure,
-  toRecordTimeLabelCloudFailureError
+  toRecordTimeLabelCloudFailureError,
+  isRecordTimeLabelOperationConflictFailure,
+  normalizeRecordTimeLabelImmutableId,
+  normalizeRecordTimeLabelPlannerId
 };