@salesforce/lds-runtime-mobile 1.428.0-dev14 → 1.428.0-dev16

package/dist/main.js

@@ -19,8 +19,9 @@ import { withRegistration, register } from '@salesforce/lds-default-luvio';
 import { setupInstrumentation, instrumentAdapter as instrumentAdapter$1, instrumentLuvio, setLdsAdaptersUiapiInstrumentation, setLdsNetworkAdapterInstrumentation } from '@salesforce/lds-instrumentation';
 import { HttpStatusCode as HttpStatusCode$1, setBypassDeepFreeze, StoreKeySet, StringKeyInMemoryStore, Reader, serializeStructuredKey, deepFreeze as deepFreeze$1, emitAdapterEvent, ingestShape, coerceConfig as coerceConfig$1, typeCheckConfig as typeCheckConfig$h, createResourceParams as createResourceParams$h, StoreKeyMap, buildNetworkSnapshotCachePolicy as buildNetworkSnapshotCachePolicy$f, resolveLink, createCustomAdapterEventEmitter, isFileReference, Environment, Luvio, InMemoryStore } from '@luvio/engine';
 import { isSupportedEntity, configuration, getObjectInfoAdapterFactory, RECORD_ID_PREFIX, RECORD_FIELDS_KEY_JUNCTION, isStoreKeyRecordViewEntity, extractRecordIdFromStoreKey, buildRecordRepKeyFromId, keyBuilderRecord, RecordRepresentationTTL, keyBuilderQuickActionExecutionRepresentation, ingestQuickActionExecutionRepresentation, getRecordId18 as getRecordId18$1, getRecordsAdapterFactory as getRecordsAdapterFactory$1, RecordRepresentationRepresentationType, ObjectInfoRepresentationType, getObjectInfosAdapterFactory, getObjectInfoDirectoryAdapterFactory, UiApiNamespace, RecordRepresentationType, RecordRepresentationVersion } from '@salesforce/lds-adapters-uiapi';
-import allowUpdatesForNonCachedRecords from '@salesforce/gate/lmr.allowUpdatesForNonCachedRecords';
+import draftQueueMaxRetryAttemptsGate from '@salesforce/gate/lmr.draft-queue-max-retry-attempts';
 import { getInstrumentation, idleDetector } from 'o11y/client';
+import allowUpdatesForNonCachedRecords from '@salesforce/gate/lmr.allowUpdatesForNonCachedRecords';
 import caseSensitiveUserId from '@salesforce/user/Id';
 import { Kind as Kind$1, visit as visit$1, isObjectType, defaultFieldResolver, buildSchema, parse as parse$8, extendSchema, isScalarType, execute, print } from '@luvio/graphql-parser';
 import graphqlRelationshipFieldsPerf from '@salesforce/gate/lds.graphqlRelationshipFieldsPerf';
@@ -2338,6 +2339,13 @@ function customActionHandler(executor, id, draftQueue) {
 }
 
 const DRAFT_SEGMENT = 'DRAFT';
+/**
+ * Metadata key under which an action's upload retry-attempt count is persisted.
+ * Lives in the action's durable `metadata` bag so the count survives app restarts
+ * (the in-memory backoff interval resets on every startQueue()). Written by the
+ * action handler on each retry and cleared when an action is manually retried.
+ */
+const DRAFT_ACTION_RETRY_COUNT_METADATA_KEY = 'retryCount';
 class DurableDraftQueue {
     getHandler(id) {
         const handler = this.handlers[id];
@@ -2696,10 +2704,14 @@ class DurableDraftQueue {
         if (!isDraftError(target)) {
             throw Error(`Action ${actionId} is not in Error state`);
         }
+        // A manual retry is a fresh start: clear the persisted upload retry-attempt
+        // count so the action doesn't immediately re-cap after a single failure.
+        const { [DRAFT_ACTION_RETRY_COUNT_METADATA_KEY]: _retryCount, ...metadataWithoutRetryCount } = target.metadata || {};
         let pendingAction = {
             ...target,
             status: DraftActionStatus.Pending,
             error: undefined,
+            metadata: metadataWithoutRetryCount,
         };
         await this.draftStore.writeAction(pendingAction);
         await this.notifyChangedListeners({
@@ -42127,6 +42139,324 @@ function makeEnvironmentUiApiRecordDraftAware(luvio, options, env) {
     return create$3(adapterSpecificEnvironments, {});
 }
 
+/**
+ * This function takes an unknown error and normalizes it to an Error object
+ */
+function normalizeError$1(error) {
+    if (typeof error === 'object' && error instanceof Error) {
+        return error;
+    }
+    else if (typeof error === 'string') {
+        return new Error(error);
+    }
+    return new Error(stringify$5(error));
+}
+/**
+ * Maximum number of times an action's upload will be retried before the action is
+ * transitioned to Error and surfaced to the consumer. Caps the otherwise-unbounded
+ * retry loop that can wedge the single-worker draft queue when an upload fails
+ * deterministically on every dispatch. Only enforced when the
+ * `lmr.draft-queue-max-retry-attempts` gate is open.
+ */
+const MAX_RETRY_ATTEMPTS = 5;
+const MAX_RETRY_ERROR_CODE = 'MAX_RETRY_ATTEMPTS_EXCEEDED';
+function isFetchResponse(failure) {
+    // The union is exactly FetchResponse | Error, so "not an Error" is the FetchResponse.
+    // This is safer than duck-typing on status/ok: a custom Error subclass that happens to
+    // carry those properties would be misclassified by a structural check.
+    return !(failure instanceof Error);
+}
+/**
+ * Builds the FetchResponse-shaped error attached to an action that has exhausted its
+ * upload retries. Shaped like a real network error response (status/statusText/ok/
+ * headers/body) so downstream consumers (DraftManager, queue instrumentation) that
+ * read `action.error.status`/`.body`/etc. behave consistently with a server error.
+ *
+ * The failure that caused the final attempt — a non-ok response (HTTP path) or a thrown
+ * error (catch path) — is folded into the body so the surfaced error says WHAT failed,
+ * not merely that the attempt cap was reached.
+ */
+function buildMaxRetryError(lastFailure) {
+    const capMessage = `Draft action exceeded ${MAX_RETRY_ATTEMPTS} upload retry attempts`;
+    if (isFetchResponse(lastFailure)) {
+        // Preserve the server's own error detail (status + body) so the surfaced error
+        // carries the last response that caused us to give up retrying.
+        return {
+            status: HttpStatusCode$1.ServerError,
+            statusText: capMessage,
+            ok: false,
+            headers: {},
+            body: {
+                errorCode: MAX_RETRY_ERROR_CODE,
+                message: `${capMessage}. Last response: status=${lastFailure.status} ${lastFailure.statusText}`,
+                lastResponseStatus: lastFailure.status,
+                lastResponseBody: lastFailure.body,
+            },
+        };
+    }
+    return {
+        status: HttpStatusCode$1.ServerError,
+        statusText: capMessage,
+        ok: false,
+        headers: {},
+        body: {
+            errorCode: MAX_RETRY_ERROR_CODE,
+            message: `${capMessage}. Last error: ${lastFailure.name}: ${lastFailure.message}`,
+            lastErrorName: lastFailure.name,
+            lastErrorMessage: lastFailure.message,
+        },
+    };
+}
+
+function attachObserversToAdapterRequestContext(observers, adapterRequestContext) {
+    if (adapterRequestContext === undefined) {
+        return { eventObservers: observers };
+    }
+    if (adapterRequestContext.eventObservers === undefined) {
+        return { ...adapterRequestContext, eventObservers: observers };
+    }
+    return {
+        ...adapterRequestContext,
+        eventObservers: adapterRequestContext.eventObservers.concat(observers),
+    };
+}
+/**
+ * Use this method to sanitize the unknown error object when
+ * we are unsure of the type of the error thrown
+ *
+ * @param err Unknown object to sanitize
+ * @returns an instance of error
+ */
+function normalizeError(err) {
+    if (err instanceof Error) {
+        return err;
+    }
+    else if (typeof err === 'string') {
+        return new Error(err);
+    }
+    return new Error(stringify$5(err));
+}
+
+const O11Y_NAMESPACE_LDS_MOBILE = 'lds-mobile';
+// metrics
+/** GraphQL */
+const GRAPHQL_EVAL_ERROR = 'gql-eval-error';
+const GRAPHQL_EVAL_DB_READ_DURATION = 'gql-eval-db-read-duration';
+const GRAPHQL_EVAL_ROOT_QUERY_COUNT = 'gql-eval-root-query-count';
+const GRAPHQL_EVAL_TOTAL_QUERY_COUNT = 'gql-eval-total-query-count';
+const GRAPHQL_EVAL_MAX_CHILD_RELATIONSHIPS_COUNT = 'gql-eval-max-child-count';
+const GRAPHQL_EVAL_QUERY_RECORD_COUNT = 'gql-eval-query-record-count';
+const GRAPHQL_SNAPSHOT_REFRESH_UNDEFINED = 'gql-snapshot-refresh-undefined';
+/** Draft Queue */
+const DRAFT_QUEUE_STATE_STARTED = 'draft-queue-state-started';
+const DRAFT_QUEUE_STATE_ERROR = 'draft-queue-state-error';
+const DRAFT_QUEUE_STATE_WAITING = 'draft-queue-state-waiting';
+const DRAFT_QUEUE_STATE_STOPPED = 'draft-queue-state-stopped';
+const DRAFT_QUEUE_ACTION_ADDED = 'draft-queue-action-added';
+const DRAFT_QUEUE_ACTION_UPLOADING = 'draft-queue-action-uploading';
+const DRAFT_QUEUE_ACTION_COMPLETED = 'draft-queue-action-completed';
+const DRAFT_QUEUE_ACTION_DELETED = 'draft-queue-action-deleted';
+const DRAFT_QUEUE_ACTION_UPDATED = 'draft-queue-action-updated';
+const DRAFT_QUEUE_ACTION_FAILED = 'draft-queue-action-failed';
+const DRAFT_QUEUE_ACTION_UPLOAD_ERROR = 'draft-queue-action-upload-error';
+const DRAFT_QUEUE_TOTAL_MERGE_ACTIONS_CALLS = 'draft-queue-total-mergeActions-calls';
+/** Content Document */
+const CREATE_CONTENT_DOCUMENT_AND_VERSION_TOTAL_SYNTHESIZE_CALLS = 'content-document-version-total-synthesize-calls';
+const CREATE_CONTENT_DOCUMENT_AND_VERSION_DRAFT_SYNTHESIZE_ERROR = 'create-content-document-version-draft-synthesize-error';
+/** Priming */
+const PRIMING_TOTAL_SESSION_COUNT = 'priming-total-session-count';
+const PRIMING_TOTAL_ERROR_COUNT = 'priming-total-error-count';
+const PRIMING_TOTAL_PRIMED_COUNT = 'priming-total-primed-count';
+const PRIMING_TOTAL_CONFLICT_COUNT = 'priming-total-conflict-count';
+// logs
+const GRAPHQL_QUERY_PARSE_ERROR = 'gql-query-parse-error';
+const GRAPHQL_SQL_EVAL_PRECONDITION_ERROR = 'gql-sql-pre-eval-error';
+const GRAPHQL_CREATE_SNAPSHOT_ERROR = 'gql-create-snapshot-error';
+const DRAFT_AWARE_CREATE_CONTENT_DOCUMENT_AND_VERSION_ERROR = 'draft-aware-create-content-document-and-version-error';
+/** Garbage Collection */
+const GARBAGE_COLLECTION_AGGRESSIVE_TRIM_COUNT = 'garbage-collection-aggressive-trim-count';
+const GARBAGE_COLLECTION_AGGRESSIVE_TRIM_RECORDS_TRIMMED = 'garbage-collection-aggressive-trim-records-trimmed';
+const GARBAGE_COLLECTION_AGGRESSIVE_TRIM_TOTAL_RECORDS_BEFORE_TRIM = 'garbage-collection-aggressive-trim-total-records-before-trim';
+const ldsMobileInstrumentation = getInstrumentation(O11Y_NAMESPACE_LDS_MOBILE);
+const nimbusLogger = typeof __nimbus !== 'undefined' &&
+    __nimbus.plugins !== undefined &&
+    __nimbus.plugins.JSLoggerPlugin !== undefined
+    ? __nimbus.plugins.JSLoggerPlugin
+    : undefined;
+function reportGraphqlQueryParseError(err) {
+    const error = normalizeError(err);
+    const errorCode = GRAPHQL_QUERY_PARSE_ERROR;
+    // Metric
+    reportGraphqlAdapterError(errorCode);
+    // Log
+    ldsMobileInstrumentation.error(error, errorCode);
+}
+function reportGraphqlSqlEvalPreconditionError(err) {
+    const error = normalizeError(err);
+    const errorCode = GRAPHQL_SQL_EVAL_PRECONDITION_ERROR;
+    // Metric
+    reportGraphqlAdapterError(errorCode);
+    // Log
+    ldsMobileInstrumentation.error(error, errorCode);
+}
+function reportGraphqlCreateSnapshotError(err) {
+    const error = normalizeError(err);
+    const errorCode = GRAPHQL_CREATE_SNAPSHOT_ERROR;
+    // Metric
+    reportGraphqlAdapterError(errorCode);
+    // Log
+    ldsMobileInstrumentation.error(error, errorCode);
+}
+function reportGraphQlEvalDbReadDuration(duration) {
+    ldsMobileInstrumentation.trackValue(GRAPHQL_EVAL_DB_READ_DURATION, duration);
+}
+function reportGraphqlAdapterError(errorCode) {
+    // Increment overall count with errorCode as tag
+    ldsMobileInstrumentation.incrementCounter(GRAPHQL_EVAL_ERROR, 1, true, { errorCode });
+}
+function reportGraphqlQueryInstrumentation(data) {
+    const queryBuckets = [1, 2, 3, 4, 5, 10, 20, 50, 100];
+    const recordBuckets = [
+        1, 5, 10, 20, 50, 100, 1000, 2000, 5000, 10000, 50000, 100000, 1000000,
+    ];
+    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_ROOT_QUERY_COUNT, data.rootQueryCount, queryBuckets);
+    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_TOTAL_QUERY_COUNT, data.totalQueryCount, queryBuckets);
+    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_MAX_CHILD_RELATIONSHIPS_COUNT, data.maxChildRelationships, queryBuckets);
+    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_QUERY_RECORD_COUNT, data.requestedRecordCount, recordBuckets);
+}
+function incrementGraphQLRefreshUndfined() {
+    ldsMobileInstrumentation.incrementCounter(GRAPHQL_SNAPSHOT_REFRESH_UNDEFINED);
+}
+function reportDraftActionEvent(state, draftCount, message) {
+    if (nimbusLogger) {
+        nimbusLogger.logInfo(`Draft action event: ${state}, depth: ${draftCount}${message ? `, message: ${message}` : ''}`);
+    }
+    switch (state) {
+        case 'added':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_ADDED);
+            break;
+        case 'uploading':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_UPLOADING);
+            break;
+        case 'completed':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_COMPLETED);
+            break;
+        case 'deleted':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_DELETED);
+            break;
+        case 'failed':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_FAILED, 1, true);
+            break;
+        case 'updated':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_UPDATED);
+            break;
+    }
+}
+/**
+ * Reports an exception thrown while uploading a draft action. The thrown error is
+ * otherwise swallowed by the upload handler's retry path, leaving the failure
+ * invisible in telemetry; this surfaces it to o11y (log + counter) so a deterministic
+ * upload failure can be diagnosed instead of silently retried forever.
+ *
+ * PII: the device log line carries only the handler id, retry attempt, and the error
+ * NAME (e.g. "TypeError") — never the free-text error message, which can embed record
+ * ids (URL path segments) or server field-validation strings. The full normalized error
+ * (message + stack) is handed only to `ldsMobileInstrumentation.error`, the structured
+ * o11y error pipeline responsible for scrubbing/handling that detail. Also does NOT log
+ * the action's targetId/tag or any request body/field values.
+ */
+function reportDraftActionUploadError(error, handlerId, attempt) {
+    const normalized = normalizeError(error);
+    if (nimbusLogger) {
+        nimbusLogger.logError(`Draft action upload error: handler=${handlerId}, attempt=${attempt}, name=${normalized.name}`);
+    }
+    ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_UPLOAD_ERROR, 1, true, {
+        handlerId,
+    });
+    ldsMobileInstrumentation.error(normalized, DRAFT_QUEUE_ACTION_UPLOAD_ERROR);
+}
+function reportDraftQueueState(state, draftCount) {
+    if (nimbusLogger) {
+        nimbusLogger.logInfo(`Draft state changed: ${state}, depth: ${draftCount}`);
+    }
+    switch (state) {
+        case 'started':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_STARTED);
+            break;
+        case 'error':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_ERROR, 1, true);
+            break;
+        case 'waiting':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_WAITING);
+            break;
+        case 'stopped':
+            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_STOPPED);
+            break;
+    }
+}
+function reportDraftAwareContentDocumentVersionSynthesizeError(err) {
+    let error;
+    if (err.body !== undefined) {
+        error = err.body;
+    }
+    else {
+        error = normalizeError(err);
+    }
+    const errorCode = DRAFT_AWARE_CREATE_CONTENT_DOCUMENT_AND_VERSION_ERROR;
+    const errorType = error.errorType;
+    const tags = {
+        errorCode,
+    };
+    if (errorType !== undefined) {
+        tags.errorType = errorType;
+    }
+    // Metric
+    ldsMobileInstrumentation.incrementCounter(CREATE_CONTENT_DOCUMENT_AND_VERSION_DRAFT_SYNTHESIZE_ERROR, 1, true, tags);
+    // Log
+    ldsMobileInstrumentation.error(error, errorCode);
+}
+function reportDraftAwareContentVersionSynthesizeCalls(mimeType) {
+    ldsMobileInstrumentation.incrementCounter(CREATE_CONTENT_DOCUMENT_AND_VERSION_TOTAL_SYNTHESIZE_CALLS, 1, undefined, { mimeType });
+}
+/** Priming */
+function reportPrimingSessionCreated() {
+    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_SESSION_COUNT, 1, undefined, {});
+}
+function reportPrimingError(errorType, recordCount) {
+    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_ERROR_COUNT, recordCount, undefined, {
+        errorType,
+    });
+}
+function reportPrimingSuccess(recordCount) {
+    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_PRIMED_COUNT, recordCount, undefined);
+}
+function reportPrimingConflict(resolutionType, recordCount) {
+    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_CONFLICT_COUNT, recordCount, undefined, {
+        resolutionType,
+    });
+}
+/** Network */
+function reportChunkCandidateUrlLength(urlLength) {
+    const buckets = [8000, 10000, 12000, 14000, 16000];
+    ldsMobileInstrumentation.bucketValue('chunk-candidate-url-length-histogram', urlLength, buckets);
+}
+/** Garbage Collection */
+function reportAggressiveTrimTriggered(trimCount, beforeTrimRecordCount, totalRecordsTrimmed) {
+    ldsMobileInstrumentation.trackValue(GARBAGE_COLLECTION_AGGRESSIVE_TRIM_COUNT, trimCount);
+    ldsMobileInstrumentation.trackValue(GARBAGE_COLLECTION_AGGRESSIVE_TRIM_TOTAL_RECORDS_BEFORE_TRIM, beforeTrimRecordCount);
+    ldsMobileInstrumentation.trackValue(GARBAGE_COLLECTION_AGGRESSIVE_TRIM_RECORDS_TRIMMED, totalRecordsTrimmed);
+}
+/** One Store Cache Purge */
+const ONESTORE_CACHE_PURGING_RECORDS_PURGED = 'onestore-cache-purging-records-purged';
+const ONESTORE_CACHE_PURGING_RECORDS_ERROR = 'onestore-cache-purging-records-error';
+function reportOneStoreRecordsPurgedFromCache(recordsPurged) {
+    ldsMobileInstrumentation.trackValue(ONESTORE_CACHE_PURGING_RECORDS_PURGED, recordsPurged);
+}
+function reportOneStoreCachePurgingError(error) {
+    const errorMessage = normalizeError(error);
+    ldsMobileInstrumentation.error(errorMessage, ONESTORE_CACHE_PURGING_RECORDS_ERROR);
+}
+
 const HTTP_HEADER_RETRY_AFTER = 'Retry-After';
 const HTTP_HEADER_IDEMPOTENCY_KEY = 'Idempotency-Key';
 const ERROR_CODE_IDEMPOTENCY_FEATURE_NOT_ENABLED = 'IDEMPOTENCY_FEATURE_NOT_ENABLED';
@@ -42277,20 +42607,89 @@ class AbstractResourceRequestActionHandler {
                 shouldRetry = true;
                 actionDataChanged = true;
             }
-            await actionErrored(shouldRetry
-                ? updatedAction
-                : {
+            if (shouldRetry) {
+                // Funnel the retry through the cap: when the gate is open this persists
+                // the attempt count and errors out once the cap is hit; when the gate is
+                // closed it behaves exactly as before. The non-ok response is the failure
+                // that would otherwise be retried.
+                await this.retryOrCap(updatedAction, response, actionErrored, retryDelayInMs, actionDataChanged);
+            }
+            else {
+                await actionErrored({
                     ...updatedAction,
                     error: response,
                     status: DraftActionStatus.Error,
-                }, shouldRetry, retryDelayInMs, actionDataChanged);
+                }, false, retryDelayInMs, actionDataChanged);
+            }
             return ProcessActionResult.ACTION_ERRORED;
         }
         catch (e) {
-            await actionErrored(action, true);
+            // #3 (ungated): the thrown exception is otherwise swallowed here, leaving a
+            // deterministic upload failure invisible in telemetry. Surface it to o11y
+            // before deciding whether to retry.
+            const error = normalizeError$1(e);
+            const attempt = this.getUploadRetryCount(action) + 1;
+            reportDraftActionUploadError(error, this.handlerId, attempt);
+            await this.retryOrCap(action, error, actionErrored);
             return ProcessActionResult.NETWORK_ERROR;
         }
     }
+    /**
+     * Reads the persisted upload retry-attempt count from the action's durable metadata
+     * bag. The count lives in metadata (rather than in-memory) so it survives app
+     * restarts and queue re-creation — the failure modes that let the unbounded retry
+     * loop run for days.
+     */
+    getUploadRetryCount(action) {
+        const parsed = Number(action.metadata?.[DRAFT_ACTION_RETRY_COUNT_METADATA_KEY]);
+        // Guard against a missing/corrupt persisted value: a NaN, fractional, or negative
+        // count must never weaken the cap. Floor to a non-negative integer, defaulting to 0.
+        if (!Number.isFinite(parsed) || parsed < 0) {
+            return 0;
+        }
+        return Math.floor(parsed);
+    }
+    /**
+     * Enforces the upload retry-attempt cap around the queue's `actionErrored` callback.
+     * Both retry paths — a retryable HTTP error and a thrown exception — funnel through
+     * here.
+     *
+     * The entire cap behavior is gated behind `lmr.draft-queue-max-retry-attempts`. When
+     * the gate is CLOSED this is a transparent passthrough: it issues the same
+     * `actionErrored(action, true, ...)` retry the queue made before this change, and
+     * writes no extra metadata. When the gate is OPEN it persists an incremented attempt
+     * count to the action's durable metadata and, once the action has failed
+     * {@link MAX_RETRY_ATTEMPTS} times, transitions it to Error (carrying a
+     * FetchResponse-shaped error that names the failure that exhausted the retries)
+     * instead of scheduling yet another retry.
+     */
+    async retryOrCap(action, lastFailure, actionErrored, retryDelayInMs, actionDataChanged) {
+        if (!draftQueueMaxRetryAttemptsGate.isOpen({ fallback: false })) {
+            // Gate closed: preserve the pre-existing unbounded-retry behavior exactly.
+            await actionErrored(action, true, retryDelayInMs, actionDataChanged);
+            return;
+        }
+        const attempt = this.getUploadRetryCount(action) + 1;
+        if (attempt >= MAX_RETRY_ATTEMPTS) {
+            await actionErrored({
+                ...action,
+                error: buildMaxRetryError(lastFailure),
+                status: DraftActionStatus.Error,
+            }, false);
+            return;
+        }
+        // Persist the incremented attempt count so it survives restarts. Forcing
+        // actionDataChanged ensures the queue writes the updated metadata before the
+        // action is rescheduled for retry.
+        const retryingAction = {
+            ...action,
+            metadata: {
+                ...action.metadata,
+                [DRAFT_ACTION_RETRY_COUNT_METADATA_KEY]: String(attempt),
+            },
+        };
+        await actionErrored(retryingAction, true, retryDelayInMs, true);
+    }
     async handleActionEnqueued(action) {
         const impactedKeys = await this.recordService.setSideEffectsForActions([action]);
         await this.recordService.reapplyRecordSideEffects(impactedKeys);
@@ -42454,6 +42853,13 @@ class AbstractResourceRequestActionHandler {
             this.isActionOfType(sourceAction)) {
             targetAction.status = DraftActionStatus.Pending;
             targetAction.data = sourceAction.data;
+            // Replacing an action's data re-queues it as a fresh upload, so the persisted
+            // upload retry-attempt count must not carry over — otherwise a previously-
+            // throttled action could immediately re-hit the cap on its first new attempt.
+            // (Mirrors the same clear in mergeActions.)
+            if (targetAction.metadata !== undefined) {
+                delete targetAction.metadata[DRAFT_ACTION_RETRY_COUNT_METADATA_KEY];
+            }
             return targetAction;
         }
         else {
@@ -42493,6 +42899,11 @@ class AbstractResourceRequestActionHandler {
         }
         // overlay metadata
         merged.metadata = { ...targetMetadata, ...sourceMetadata };
+        // A merge folds new user data into the action and re-queues it as a fresh upload,
+        // so the persisted upload retry-attempt count must not carry over — otherwise a
+        // previously-throttled action could immediately re-hit the cap on its first new
+        // attempt.
+        delete merged.metadata[DRAFT_ACTION_RETRY_COUNT_METADATA_KEY];
         // put status back to pending to auto upload if queue is active and targed is at the head.
         merged.status = DraftActionStatus.Pending;
         return merged;
@@ -43103,231 +43514,6 @@ class AbstractQuickActionHandler extends AbstractResourceRequestActionHandler {
     }
 }
 
-function attachObserversToAdapterRequestContext(observers, adapterRequestContext) {
-    if (adapterRequestContext === undefined) {
-        return { eventObservers: observers };
-    }
-    if (adapterRequestContext.eventObservers === undefined) {
-        return { ...adapterRequestContext, eventObservers: observers };
-    }
-    return {
-        ...adapterRequestContext,
-        eventObservers: adapterRequestContext.eventObservers.concat(observers),
-    };
-}
-/**
- * Use this method to sanitize the unknown error object when
- * we are unsure of the type of the error thrown
- *
- * @param err Unknown object to sanitize
- * @returns an instance of error
- */
-function normalizeError(err) {
-    if (err instanceof Error) {
-        return err;
-    }
-    else if (typeof err === 'string') {
-        return new Error(err);
-    }
-    return new Error(stringify$5(err));
-}
-
-const O11Y_NAMESPACE_LDS_MOBILE = 'lds-mobile';
-// metrics
-/** GraphQL */
-const GRAPHQL_EVAL_ERROR = 'gql-eval-error';
-const GRAPHQL_EVAL_DB_READ_DURATION = 'gql-eval-db-read-duration';
-const GRAPHQL_EVAL_ROOT_QUERY_COUNT = 'gql-eval-root-query-count';
-const GRAPHQL_EVAL_TOTAL_QUERY_COUNT = 'gql-eval-total-query-count';
-const GRAPHQL_EVAL_MAX_CHILD_RELATIONSHIPS_COUNT = 'gql-eval-max-child-count';
-const GRAPHQL_EVAL_QUERY_RECORD_COUNT = 'gql-eval-query-record-count';
-const GRAPHQL_SNAPSHOT_REFRESH_UNDEFINED = 'gql-snapshot-refresh-undefined';
-/** Draft Queue */
-const DRAFT_QUEUE_STATE_STARTED = 'draft-queue-state-started';
-const DRAFT_QUEUE_STATE_ERROR = 'draft-queue-state-error';
-const DRAFT_QUEUE_STATE_WAITING = 'draft-queue-state-waiting';
-const DRAFT_QUEUE_STATE_STOPPED = 'draft-queue-state-stopped';
-const DRAFT_QUEUE_ACTION_ADDED = 'draft-queue-action-added';
-const DRAFT_QUEUE_ACTION_UPLOADING = 'draft-queue-action-uploading';
-const DRAFT_QUEUE_ACTION_COMPLETED = 'draft-queue-action-completed';
-const DRAFT_QUEUE_ACTION_DELETED = 'draft-queue-action-deleted';
-const DRAFT_QUEUE_ACTION_UPDATED = 'draft-queue-action-updated';
-const DRAFT_QUEUE_ACTION_FAILED = 'draft-queue-action-failed';
-const DRAFT_QUEUE_TOTAL_MERGE_ACTIONS_CALLS = 'draft-queue-total-mergeActions-calls';
-/** Content Document */
-const CREATE_CONTENT_DOCUMENT_AND_VERSION_TOTAL_SYNTHESIZE_CALLS = 'content-document-version-total-synthesize-calls';
-const CREATE_CONTENT_DOCUMENT_AND_VERSION_DRAFT_SYNTHESIZE_ERROR = 'create-content-document-version-draft-synthesize-error';
-/** Priming */
-const PRIMING_TOTAL_SESSION_COUNT = 'priming-total-session-count';
-const PRIMING_TOTAL_ERROR_COUNT = 'priming-total-error-count';
-const PRIMING_TOTAL_PRIMED_COUNT = 'priming-total-primed-count';
-const PRIMING_TOTAL_CONFLICT_COUNT = 'priming-total-conflict-count';
-// logs
-const GRAPHQL_QUERY_PARSE_ERROR = 'gql-query-parse-error';
-const GRAPHQL_SQL_EVAL_PRECONDITION_ERROR = 'gql-sql-pre-eval-error';
-const GRAPHQL_CREATE_SNAPSHOT_ERROR = 'gql-create-snapshot-error';
-const DRAFT_AWARE_CREATE_CONTENT_DOCUMENT_AND_VERSION_ERROR = 'draft-aware-create-content-document-and-version-error';
-/** Garbage Collection */
-const GARBAGE_COLLECTION_AGGRESSIVE_TRIM_COUNT = 'garbage-collection-aggressive-trim-count';
-const GARBAGE_COLLECTION_AGGRESSIVE_TRIM_RECORDS_TRIMMED = 'garbage-collection-aggressive-trim-records-trimmed';
-const GARBAGE_COLLECTION_AGGRESSIVE_TRIM_TOTAL_RECORDS_BEFORE_TRIM = 'garbage-collection-aggressive-trim-total-records-before-trim';
-const ldsMobileInstrumentation = getInstrumentation(O11Y_NAMESPACE_LDS_MOBILE);
-const nimbusLogger = typeof __nimbus !== 'undefined' &&
-    __nimbus.plugins !== undefined &&
-    __nimbus.plugins.JSLoggerPlugin !== undefined
-    ? __nimbus.plugins.JSLoggerPlugin
-    : undefined;
-function reportGraphqlQueryParseError(err) {
-    const error = normalizeError(err);
-    const errorCode = GRAPHQL_QUERY_PARSE_ERROR;
-    // Metric
-    reportGraphqlAdapterError(errorCode);
-    // Log
-    ldsMobileInstrumentation.error(error, errorCode);
-}
-function reportGraphqlSqlEvalPreconditionError(err) {
-    const error = normalizeError(err);
-    const errorCode = GRAPHQL_SQL_EVAL_PRECONDITION_ERROR;
-    // Metric
-    reportGraphqlAdapterError(errorCode);
-    // Log
-    ldsMobileInstrumentation.error(error, errorCode);
-}
-function reportGraphqlCreateSnapshotError(err) {
-    const error = normalizeError(err);
-    const errorCode = GRAPHQL_CREATE_SNAPSHOT_ERROR;
-    // Metric
-    reportGraphqlAdapterError(errorCode);
-    // Log
-    ldsMobileInstrumentation.error(error, errorCode);
-}
-function reportGraphQlEvalDbReadDuration(duration) {
-    ldsMobileInstrumentation.trackValue(GRAPHQL_EVAL_DB_READ_DURATION, duration);
-}
-function reportGraphqlAdapterError(errorCode) {
-    // Increment overall count with errorCode as tag
-    ldsMobileInstrumentation.incrementCounter(GRAPHQL_EVAL_ERROR, 1, true, { errorCode });
-}
-function reportGraphqlQueryInstrumentation(data) {
-    const queryBuckets = [1, 2, 3, 4, 5, 10, 20, 50, 100];
-    const recordBuckets = [
-        1, 5, 10, 20, 50, 100, 1000, 2000, 5000, 10000, 50000, 100000, 1000000,
-    ];
-    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_ROOT_QUERY_COUNT, data.rootQueryCount, queryBuckets);
-    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_TOTAL_QUERY_COUNT, data.totalQueryCount, queryBuckets);
-    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_MAX_CHILD_RELATIONSHIPS_COUNT, data.maxChildRelationships, queryBuckets);
-    ldsMobileInstrumentation.bucketValue(GRAPHQL_EVAL_QUERY_RECORD_COUNT, data.requestedRecordCount, recordBuckets);
-}
-function incrementGraphQLRefreshUndfined() {
-    ldsMobileInstrumentation.incrementCounter(GRAPHQL_SNAPSHOT_REFRESH_UNDEFINED);
-}
-function reportDraftActionEvent(state, draftCount, message) {
-    if (nimbusLogger) {
-        nimbusLogger.logInfo(`Draft action event: ${state}, depth: ${draftCount}${message ? `, message: ${message}` : ''}`);
-    }
-    switch (state) {
-        case 'added':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_ADDED);
-            break;
-        case 'uploading':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_UPLOADING);
-            break;
-        case 'completed':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_COMPLETED);
-            break;
-        case 'deleted':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_DELETED);
-            break;
-        case 'failed':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_FAILED, 1, true);
-            break;
-        case 'updated':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_ACTION_UPDATED);
-            break;
-    }
-}
-function reportDraftQueueState(state, draftCount) {
-    if (nimbusLogger) {
-        nimbusLogger.logInfo(`Draft state changed: ${state}, depth: ${draftCount}`);
-    }
-    switch (state) {
-        case 'started':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_STARTED);
-            break;
-        case 'error':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_ERROR, 1, true);
-            break;
-        case 'waiting':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_WAITING);
-            break;
-        case 'stopped':
-            ldsMobileInstrumentation.incrementCounter(DRAFT_QUEUE_STATE_STOPPED);
-            break;
-    }
-}
-function reportDraftAwareContentDocumentVersionSynthesizeError(err) {
-    let error;
-    if (err.body !== undefined) {
-        error = err.body;
-    }
-    else {
-        error = normalizeError(err);
-    }
-    const errorCode = DRAFT_AWARE_CREATE_CONTENT_DOCUMENT_AND_VERSION_ERROR;
-    const errorType = error.errorType;
-    const tags = {
-        errorCode,
-    };
-    if (errorType !== undefined) {
-        tags.errorType = errorType;
-    }
-    // Metric
-    ldsMobileInstrumentation.incrementCounter(CREATE_CONTENT_DOCUMENT_AND_VERSION_DRAFT_SYNTHESIZE_ERROR, 1, true, tags);
-    // Log
-    ldsMobileInstrumentation.error(error, errorCode);
-}
-function reportDraftAwareContentVersionSynthesizeCalls(mimeType) {
-    ldsMobileInstrumentation.incrementCounter(CREATE_CONTENT_DOCUMENT_AND_VERSION_TOTAL_SYNTHESIZE_CALLS, 1, undefined, { mimeType });
-}
-/** Priming */
-function reportPrimingSessionCreated() {
-    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_SESSION_COUNT, 1, undefined, {});
-}
-function reportPrimingError(errorType, recordCount) {
-    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_ERROR_COUNT, recordCount, undefined, {
-        errorType,
-    });
-}
-function reportPrimingSuccess(recordCount) {
-    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_PRIMED_COUNT, recordCount, undefined);
-}
-function reportPrimingConflict(resolutionType, recordCount) {
-    ldsMobileInstrumentation.incrementCounter(PRIMING_TOTAL_CONFLICT_COUNT, recordCount, undefined, {
-        resolutionType,
-    });
-}
-/** Network */
-function reportChunkCandidateUrlLength(urlLength) {
-    const buckets = [8000, 10000, 12000, 14000, 16000];
-    ldsMobileInstrumentation.bucketValue('chunk-candidate-url-length-histogram', urlLength, buckets);
-}
-/** Garbage Collection */
-function reportAggressiveTrimTriggered(trimCount, beforeTrimRecordCount, totalRecordsTrimmed) {
-    ldsMobileInstrumentation.trackValue(GARBAGE_COLLECTION_AGGRESSIVE_TRIM_COUNT, trimCount);
-    ldsMobileInstrumentation.trackValue(GARBAGE_COLLECTION_AGGRESSIVE_TRIM_TOTAL_RECORDS_BEFORE_TRIM, beforeTrimRecordCount);
-    ldsMobileInstrumentation.trackValue(GARBAGE_COLLECTION_AGGRESSIVE_TRIM_RECORDS_TRIMMED, totalRecordsTrimmed);
-}
-/** One Store Cache Purge */
-const ONESTORE_CACHE_PURGING_RECORDS_PURGED = 'onestore-cache-purging-records-purged';
-const ONESTORE_CACHE_PURGING_RECORDS_ERROR = 'onestore-cache-purging-records-error';
-function reportOneStoreRecordsPurgedFromCache(recordsPurged) {
-    ldsMobileInstrumentation.trackValue(ONESTORE_CACHE_PURGING_RECORDS_PURGED, recordsPurged);
-}
-function reportOneStoreCachePurgingError(error) {
-    const errorMessage = normalizeError(error);
-    ldsMobileInstrumentation.error(errorMessage, ONESTORE_CACHE_PURGING_RECORDS_ERROR);
-}
-
 const QUICK_ACTION_HANDLER = 'QUICK_ACTION_HANDLER';
 class QuickActionExecutionRepresentationHandler extends AbstractQuickActionHandler {
     constructor(getLuvio, draftRecordService, draftQueue, networkAdapter, isDraftId, sideEffectService, objectInfoService, getRecord) {
@@ -58934,7 +59120,7 @@ function buildServiceDescriptor$b(luvio) {
         },
     };
 }
-// version: 1.428.0-dev14-450676496d
+// version: 1.428.0-dev16-07fd0f90d6
 
 /**
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -58960,7 +59146,7 @@ function buildServiceDescriptor$a(notifyRecordUpdateAvailable, getNormalizedLuvi
         },
     };
 }
-// version: 1.428.0-dev14-450676496d
+// version: 1.428.0-dev16-07fd0f90d6
 
 /*!
  * Copyright (c) 2022, Salesforce, Inc.,
@@ -61697,4 +61883,4 @@ register({
 });
 
 export { O11Y_NAMESPACE_LDS_MOBILE, getRuntime, ingest$1o as ingestDenormalizedRecordRepresentation, initializeOneStore, registerReportObserver, reportGraphqlQueryParseError };
-// version: 1.428.0-dev14-d04322589b
+// version: 1.428.0-dev16-22ad12fb68