@recordtimelabel/core 0.6.1 → 0.6.4

package/src/protocol.js

@@ -17,12 +17,560 @@ 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',
+  AUTH_TRANSITION_REQUIRED: 'auth-transition-required',
+  TERMINAL: 'terminal',
+  STALE_SESSION: 'stale-session'
+});
+
+const CLOUD_FAILURE_CLASS_VALUES = new Set(Object.values(RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES));
+
+// 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'
 ]);
 
+// 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],
+  ['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],
+  ['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],
+  ...[...OPERATION_CONFLICT_CODES].map((code) => [
+    code,
+    RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.TERMINAL
+  ])
+]);
+
+const pickFailureText = (...values) => {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  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 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) => {
+  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;
+  const retryAfterMs = Number(value);
+  return Number.isFinite(retryAfterMs) && retryAfterMs >= 0 ? retryAfterMs : null;
+};
+
+const looksLikeNetworkFailure = (source) => {
+  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(
+    blob.includes('failed to fetch') ||
+    blob.includes('fetch 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) => {
+  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 (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 (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) {
+    return RECORD_TIMELABEL_CLOUD_FAILURE_CLASSES.BOOTSTRAP_REQUIRED;
+  }
+  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)
+  ) {
+    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
+ * strings; this helper only preserves metadata and assigns one class.
+ */
+export const normalizeRecordTimeLabelCloudFailure = (input = {}) => {
+  const source = unwrapFailureSource(input);
+  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 failureClass = classifyRecordTimeLabelCloudFailure(source, status);
+  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;
+  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,
+    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.schemaVersion = failure.schemaVersion;
+  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;
+  error.requestId = failure.requestId;
+  Object.defineProperty(error, 'failure', {
+    value: failure,
+    enumerable: false,
+    configurable: true
+  });
+  return error;
+};
+
 const ALLOWED_OPERATION_RESULT_STATUSES = new Set(
   Object.values(RECORD_TIMELABEL_OPERATION_RESULT_STATUSES)
 );
@@ -136,6 +684,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 || (
@@ -269,10 +818,21 @@ 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_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,
   buildRecordTimeLabelRequestId,
   createRecordTimeLabelTransportFailureResults,
   normalizeRecordTimeLabelOperationResults,
-  normalizeRecordTimeLabelEnvelopeResponse
+  normalizeRecordTimeLabelEnvelopeResponse,
+  normalizeRecordTimeLabelCloudFailure,
+  toRecordTimeLabelCloudFailureError,
+  isRecordTimeLabelOperationConflictFailure,
+  normalizeRecordTimeLabelImmutableId,
+  normalizeRecordTimeLabelPlannerId
 };