@atlaskit/editor-synced-block-provider 8.1.10 → 8.3.0

package/dist/cjs/utils/errorHandling.js

@@ -4,7 +4,10 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.updateSuccessPayload = exports.updateReferenceErrorPayload = exports.updateErrorPayload = exports.updateCacheErrorPayload = exports.stringifyError = exports.sourceInfoOrphanedPayload = exports.getSourceInfoErrorPayload = exports.getErrorPayload = exports.fetchSuccessPayload = exports.fetchReferencesErrorPayload = exports.fetchErrorPayload = exports.deleteSuccessPayload = exports.deleteErrorPayload = exports.createSuccessPayloadNew = exports.createSuccessPayload = exports.createErrorPayload = exports.classifyErrorReason = exports.cacheDeletionForcedPayload = exports.buildErrorAttribution = void 0;
+exports.fetchSuccessPayload = exports.fetchReferencesErrorPayload = exports.fetchErrorPayload = exports.deleteSuccessPayload = exports.deleteErrorPayload = exports.createSuccessPayloadNew = exports.createSuccessPayload = exports.createErrorPayload = exports.classifyFetchErrorReason = exports.classifyErrorReason = exports.cacheDeletionForcedPayload = exports.buildFetchErrorAttribution = exports.buildErrorAttribution = exports.FETCH_BENIGN_REASONS = void 0;
+exports.getErrorPayload = getErrorPayload;
+exports.updateSuccessPayload = exports.updateReferenceErrorPayload = exports.updateErrorPayload = exports.updateCacheErrorPayload = exports.stringifyError = exports.sourceInfoOrphanedPayload = exports.getSourceInfoErrorPayload = void 0;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _analytics = require("@atlaskit/editor-common/analytics");
 var _types = require("../common/types");
@@ -67,19 +70,155 @@ var buildErrorAttribution = exports.buildErrorAttribution = function buildErrorA
   });
 };
 
+/**
+ * The set of categorical failure reasons emitted on synced-block fetch/subscribe
+ * operational error events (EDITOR-7862). Extends the write-path
+ * {@link SyncBlockErrorReason} set with read-path-specific buckets so the analytics
+ * dashboard can break fetch failures down by cause instead of regex-matching the
+ * free-text `error` blob.
+ *
+ * The read path surfaces several causes the write-path `SyncBlockError` enum does not
+ * model (benign source-state transitions, permission denials, WebSocket lifecycle, and
+ * client-side readiness errors), so those are added here. Known `SyncBlockError` enum
+ * values (`not_found`, `forbidden`, ...) still pass through unchanged.
+ */
+
+/**
+ * Fetch reasons that represent benign (working-as-designed) outcomes rather than genuine
+ * system failures. The dashboard uses this to compute a "true error rate" by excluding
+ * benign reasons via the structured `reason` attribute instead of brittle free-text regex
+ * (EDITOR-7862).
+ */
+var FETCH_BENIGN_REASONS = exports.FETCH_BENIGN_REASONS = new Set(['source_deleted', 'source_unpublished', 'source_unsynced', 'source_not_found', 'permission_denied', 'unauthenticated',
+// Mirror the benign write-path enum equivalents so already-classified errors are
+// treated consistently.
+'not_found', 'forbidden', 'unpublished'
+// NOTE: `entity_not_found` and `offline` are intentionally NOT benign.
+// - `entity_not_found` is retried up to ENTITY_NOT_FOUND_MAX_RETRIES (analytics are
+//   suppressed during retries); by the time the error event fires, retries are
+//   exhausted and it is a genuine failure.
+// - `offline` is genuine client connectivity loss, not a working-as-designed outcome.
+// Both still emit `reason` (so they can be inspected) but are counted as true errors.
+]);
+
+/**
+ * Ordered list of substring matchers mapping known free-text fetch/subscribe error
+ * strings to a categorical {@link SyncBlockFetchErrorReason}. Each entry is a list of
+ * lowercase needles; if ANY needle is found (case-insensitively) in the raw `error`
+ * string, the entry's reason is used. Order matters: more specific entries must precede
+ * more general ones.
+ *
+ * Plain `String.includes` substring matching is used deliberately instead of `RegExp`:
+ * it sidesteps the `require-unicode-regexp` lint rule AND the declaration build's lower
+ * compile target (which rejects the regex `u` flag with TS1501), while being faster and
+ * easier to read. Doing this classification in code (rather than in dashboard SQL) keeps
+ * the buckets versioned with the source strings that produce them (EDITOR-7862).
+ */
+var FETCH_REASON_MATCHERS = [
+// Benign: source-state transitions (deletionReason values + free text).
+[['source-document-deleted'], 'source_deleted'], [['source-block-deleted'], 'source_deleted'], [['source-block-unpublished'], 'source_unpublished'], [['source-block-unsynced'], 'source_unsynced'], [['does not exist'], 'source_not_found'], [['unpublished'], 'source_unpublished'],
+// Working-as-designed permission outcomes.
+[['unauthenticated'], 'unauthenticated'], [['not permitted to read synced block'], 'permission_denied'], [['bulk permission check failed'], 'permission_denied'], [['permission denied'], 'permission_denied'],
+// Genuine system failures.
+[['reconnection failed after'], 'websocket_exhausted'],
+// `reconnect to the subscription` (not a bare `reconnect`) avoids false positives on
+// unrelated DB/GraphQL "reconnect" messages while still matching the WS-drop string.
+[['websocket', 'reconnect to the subscription', 'subscription terminated'], 'websocket_drop'], [['429', 'rate limit', 'rate-limit', 'ratelimit'], 'rate_limited'],
+// `econnrefused`/`econnreset` (not a bare `econn`, which would also match `reconnect`).
+[['network', 'failed to fetch', 'econnrefused', 'econnreset', 'timed out', 'timeout'], 'network'], [['data provider not set'], 'data_provider_not_ready']];
+
+/**
+ * Maps a fetch/subscribe `error` field — which may be a {@link SyncBlockError} enum
+ * value, a {@link DeletionReason} value, or an arbitrary free-text/JSON blob — to a
+ * stable categorical {@link SyncBlockFetchErrorReason} for analytics grouping.
+ *
+ * Resolution order:
+ * 1. Known `SyncBlockError` enum value → passed through (via {@link classifyErrorReason}).
+ * 2. Known free-text substring → mapped to a fetch-specific bucket.
+ * 3. Anything else (including opaque blobs like `errored`-only payloads or
+ *    `ErrorEvent: "undefined"`) → `'unknown'`, so the dashboard never groups on free text.
+ *
+ * Note: the bare string `'errored'` IS a `SyncBlockError` enum value and therefore
+ * classifies as `'errored'` (not `'unknown'`); only genuinely unrecognised strings
+ * collapse to `'unknown'`.
+ */
+var classifyFetchErrorReason = exports.classifyFetchErrorReason = function classifyFetchErrorReason(error) {
+  var enumReason = classifyErrorReason(error);
+  if (enumReason !== 'unknown') {
+    return enumReason;
+  }
+  if (error) {
+    var haystack = error.toLowerCase();
+    for (var _i = 0, _FETCH_REASON_MATCHER = FETCH_REASON_MATCHERS; _i < _FETCH_REASON_MATCHER.length; _i++) {
+      var _FETCH_REASON_MATCHER2 = (0, _slicedToArray2.default)(_FETCH_REASON_MATCHER[_i], 2),
+        needles = _FETCH_REASON_MATCHER2[0],
+        reason = _FETCH_REASON_MATCHER2[1];
+      if (needles.some(function (needle) {
+        return haystack.includes(needle);
+      })) {
+        return reason;
+      }
+    }
+  }
+  return 'unknown';
+};
+
+/**
+ * Extra, optional analytics attributes describing WHY a fetch/subscribe synced-block
+ * action failed. Spread conditionally so we never emit `undefined` keys (EDITOR-7862).
+ *
+ * Adds `benign` on top of the shared {@link ErrorAttributionAttributes} so the dashboard
+ * can compute a true error rate (`genuine / total`) without any free-text regex.
+ */
+
+/**
+ * Builds the {@link FetchErrorAttributionAttributes} for a failed fetch/subscribe
+ * synced-block operation from the raw `error` field and optional backend `statusCode`.
+ * Returns `undefined` when the `platform_editor_blocks_patch_3` gate is OFF, so the new
+ * `reason`/`statusCode`/`benign` attributes are only emitted once the gate is rolled out
+ * (EDITOR-7862). The existing free-text `error` attribute is always left unchanged.
+ *
+ * `gateEnabled` is injected by the caller (the store managers evaluate `fg(...)`) so this
+ * helper stays pure and trivially unit-testable for both gate states.
+ */
+var buildFetchErrorAttribution = exports.buildFetchErrorAttribution = function buildFetchErrorAttribution(gateEnabled, error, statusCode) {
+  if (!gateEnabled) {
+    return undefined;
+  }
+  var reason = classifyFetchErrorReason(error);
+  return _objectSpread({
+    reason: reason,
+    benign: FETCH_BENIGN_REASONS.has(reason)
+  }, statusCode !== undefined && {
+    statusCode: statusCode
+  });
+};
+
 // `sourceProduct` is threaded through every helper so analytics
 // events can be attributed to the source product (`confluence-page` vs `jira-work-item`).
 // All helpers accept it as an optional trailing argument; the spread-only-when-truthy
 // pattern below ensures we never emit `sourceProduct: undefined` (which would dirty the
 // event schema with empty keys).
 
-var getErrorPayload = exports.getErrorPayload = function getErrorPayload(actionSubjectId, error, resourceId, sourceProduct, attribution) {
+/**
+ * Shared operational ERROR payload builder for synced-block events.
+ *
+ * Overloaded so the emitted `reason` type stays accurate per path (raised in review on
+ * EDITOR-7862): fetch/subscribe callers pass a {@link FetchErrorAttributionAttributes}
+ * (discriminated by its required `benign` field) and get the wider
+ * {@link SyncBlockFetchErrorReason}; write-path callers pass an
+ * {@link ErrorAttributionAttributes} (or nothing) and keep the narrower
+ * {@link SyncBlockErrorReason}, so write-path payloads never claim to carry fetch-only
+ * buckets like `source_deleted` they never emit.
+ */
+
+function getErrorPayload(actionSubjectId, error, resourceId, sourceProduct, attribution) {
   return {
     action: _analytics.ACTION.ERROR,
     actionSubject: _analytics.ACTION_SUBJECT.SYNCED_BLOCK,
     actionSubjectId: actionSubjectId,
     eventType: _analytics.EVENT_TYPE.OPERATIONAL,
-    attributes: _objectSpread(_objectSpread(_objectSpread(_objectSpread({
+    attributes: _objectSpread(_objectSpread(_objectSpread(_objectSpread(_objectSpread({
       error: error
     }, resourceId && {
       resourceId: resourceId
@@ -89,11 +228,18 @@ var getErrorPayload = exports.getErrorPayload = function getErrorPayload(actionS
       reason: attribution.reason
     }), (attribution === null || attribution === void 0 ? void 0 : attribution.statusCode) !== undefined && {
       statusCode: attribution.statusCode
+    }), attribution && 'benign' in attribution && {
+      benign: attribution.benign
     })
   };
-};
-var fetchErrorPayload = exports.fetchErrorPayload = function fetchErrorPayload(error, resourceId, sourceProduct) {
-  return getErrorPayload(_analytics.ACTION_SUBJECT_ID.SYNCED_BLOCK_FETCH, error, resourceId, sourceProduct);
+}
+var fetchErrorPayload = exports.fetchErrorPayload = function fetchErrorPayload(error, resourceId, sourceProduct, attribution) {
+  return (
+    // Branch on attribution presence so each call resolves to a concrete overload: with
+    // attribution it hits the fetch overload (wider `reason`); without it (gate OFF) it
+    // hits the no-attribution overload. Both produce a fetch event regardless.
+    attribution ? getErrorPayload(_analytics.ACTION_SUBJECT_ID.SYNCED_BLOCK_FETCH, error, resourceId, sourceProduct, attribution) : getErrorPayload(_analytics.ACTION_SUBJECT_ID.SYNCED_BLOCK_FETCH, error, resourceId, sourceProduct)
+  );
 };
 var getSourceInfoErrorPayload = exports.getSourceInfoErrorPayload = function getSourceInfoErrorPayload(error, resourceId, sourceProduct) {
   return getErrorPayload(_analytics.ACTION_SUBJECT_ID.SYNCED_BLOCK_GET_SOURCE_INFO, error, resourceId, sourceProduct);

package/dist/es2019/common/types.js

@@ -1,3 +1,4 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
 export let SyncBlockError = /*#__PURE__*/function (SyncBlockError) {
   SyncBlockError["Errored"] = "errored";
   SyncBlockError["NotFound"] = "not_found";
@@ -16,4 +17,49 @@ export let SyncBlockError = /*#__PURE__*/function (SyncBlockError) {
   // block does not exist on this site (e.g. cross-site reference or hard deleted)
   SyncBlockError["EntityNotFound"] = "entity_not_found";
   return SyncBlockError;
-}({});
+}({});
+/**
+ * Helpers to distinguish "data provider not ready / torn down" from a genuine
+ * fetch/subscribe failure (EDITOR-7860). On Jira the provider is wired
+ * asynchronously and `destroy()` nulls it on orphaned managers, so queued/
+ * in-flight ops throw `Data provider not set` — previously mis-logged as a real
+ * error. These let throw and catch sites agree on one non-string-matched signal
+ * so the residual false errors are suppressed. Gated by
+ * `platform_editor_blocks_patch_3`.
+ *
+ * NB: these intentionally live here rather than in a dedicated module to avoid
+ * adding a downstream file to consuming Jira packages' Thunderstone complexity.
+ */
+
+/** Legacy message — kept identical for gate-off and historical events. */
+export const PROVIDER_NOT_READY_MESSAGE = 'Data provider not set';
+
+/**
+ * Thrown when a fetch/subscribe runs against a manager whose provider is not
+ * (yet) available or torn down. Keeps the legacy message + name so string
+ * matchers still work, while new code uses {@link isProviderNotReadyError}.
+ */
+export class ProviderNotReadyError extends Error {
+  constructor(message = PROVIDER_NOT_READY_MESSAGE) {
+    super(message);
+    _defineProperty(this, "isProviderNotReadyError", true);
+    this.name = 'ProviderNotReadyError';
+    // Restore prototype chain so instanceof works after transpilation.
+    Object.setPrototypeOf(this, ProviderNotReadyError.prototype);
+  }
+}
+
+/**
+ * True when the value is a "provider not ready / torn down" condition, not a
+ * genuine failure. Recognises the tagged {@link ProviderNotReadyError} and the
+ * legacy message (for errors thrown before rollout).
+ */
+export const isProviderNotReadyError = error => {
+  if (error instanceof ProviderNotReadyError) {
+    return true;
+  }
+  if (typeof error === 'object' && error !== null && error.isProviderNotReadyError === true) {
+    return true;
+  }
+  return error instanceof Error && error.message === PROVIDER_NOT_READY_MESSAGE;
+};

package/dist/es2019/hooks/useFetchSyncBlockData.js

@@ -1,10 +1,12 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { isSSR } from '@atlaskit/editor-common/core-utils';
 import { logException } from '@atlaskit/editor-common/monitoring';
-import { SyncBlockError } from '../common/types';
-import { fetchErrorPayload } from '../utils/errorHandling';
+import { fg } from '@atlaskit/platform-feature-flags';
+import { isProviderNotReadyError, SyncBlockError } from '../common/types';
+import { buildFetchErrorAttribution, fetchErrorPayload } from '../utils/errorHandling';
 import { createSyncBlockNode, getSourceProductFromResourceIdSafe } from '../utils/utils';
 export const useFetchSyncBlockData = (manager, resourceId, localId, fireAnalyticsEvent) => {
+  var _manager$referenceMan2, _manager$referenceMan3, _manager$referenceMan4;
   // Initialize both states from a single cache lookup to avoid race conditions.
   // When a block is moved/remounted, the old component's cleanup may clear the cache
   // before or after the new component mounts. By doing a single lookup, we ensure
@@ -26,10 +28,23 @@ export const useFetchSyncBlockData = (manager, resourceId, localId, fireAnalytic
       isLoading: true
     };
   });
+
+  // On Jira the data provider is wired asynchronously, so the manager can be
+  // constructed with `dataProvider === undefined`. Fetching/subscribing in that
+  // window throws `Data provider not set`, logged as a false fetch error
+  // (EDITOR-7860). Gate on readiness; once the provider resolves a new manager
+  // instance is created so `referenceManager` changes identity and the effect
+  // below re-runs, subscribing exactly once.
+  const isDataProviderReady = fg('platform_editor_blocks_patch_3') ? (_manager$referenceMan2 = (_manager$referenceMan3 = (_manager$referenceMan4 = manager.referenceManager).hasDataProvider) === null || _manager$referenceMan3 === void 0 ? void 0 : _manager$referenceMan3.call(_manager$referenceMan4)) !== null && _manager$referenceMan2 !== void 0 ? _manager$referenceMan2 : false : true;
   const reloadData = useCallback(async () => {
     if (isLoading) {
       return;
     }
+
+    // Not ready: skip fetch, emit no error (see readiness note above).
+    if (!isDataProviderReady) {
+      return;
+    }
     try {
       const syncBlockNode = resourceId && localId ? createSyncBlockNode(localId, resourceId) : null;
       if (!syncBlockNode) {
@@ -43,10 +58,21 @@ export const useFetchSyncBlockData = (manager, resourceId, localId, fireAnalytic
       // Fetch sync block data, the `subscribeToSyncBlock` will update the state once data is fetched
       await manager.referenceManager.fetchSyncBlocksData([syncBlockNode]);
     } catch (error) {
+      // EDITOR-7860: benign not-ready throw — emit no error and stay loading
+      // so it resolves on retry once the provider is wired. Checked before
+      // `logException` so the benign case produces no exception-tracker noise.
+      // Gate-off behaviour is unchanged.
+      if (isProviderNotReadyError(error) && fg('platform_editor_blocks_patch_3')) {
+        setFetchState(prev => ({
+          ...prev,
+          isLoading: true
+        }));
+        return;
+      }
       logException(error, {
         location: 'editor-synced-block-provider/useFetchSyncBlockData'
       });
-      fireAnalyticsEvent === null || fireAnalyticsEvent === void 0 ? void 0 : fireAnalyticsEvent(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId)));
+      fireAnalyticsEvent === null || fireAnalyticsEvent === void 0 ? void 0 : fireAnalyticsEvent(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), error.message)));
 
       // Set error state if fetching fails
       setFetchState({
@@ -64,13 +90,20 @@ export const useFetchSyncBlockData = (manager, resourceId, localId, fireAnalytic
       ...prev,
       isLoading: false
     }));
-  }, [isLoading, localId, manager.referenceManager, resourceId, fireAnalyticsEvent]);
+  }, [isLoading, isDataProviderReady, localId, manager.referenceManager, resourceId, fireAnalyticsEvent]);
   useEffect(() => {
     if (isSSR()) {
       // in SSR, we don't need to subscribe to updates,
       // instead we rely on pre-fetched data ONLY, see initialization of syncBlockInstance above
       return;
     }
+
+    // Not ready: skip subscribe (it would trigger a batched fetch and a false
+    // error) and keep `isLoading: true`. `isDataProviderReady` is in the deps,
+    // so the effect re-runs and subscribes once the provider resolves.
+    if (!isDataProviderReady) {
+      return;
+    }
     const unsubscribe = manager.referenceManager.subscribeToSyncBlock(resourceId || '', localId || '', data => {
       setFetchState({
         syncBlockInstance: data,
@@ -80,7 +113,7 @@ export const useFetchSyncBlockData = (manager, resourceId, localId, fireAnalytic
     return () => {
       unsubscribe();
     };
-  }, [localId, manager.referenceManager, resourceId]);
+  }, [isDataProviderReady, localId, manager.referenceManager, resourceId]);
   const ssrProviders = useMemo(() => {
     return resourceId ? manager.referenceManager.getSSRProviders(resourceId) : null;
   }, [resourceId, manager.referenceManager]);

package/dist/es2019/providers/block-service/blockServiceAPI.js

@@ -300,11 +300,16 @@ export const batchFetchData = async (cloudId, parentAri, blockNodeIdentifiers, c
       }));
     }
 
-    // If batch request fails, return error for all resourceIds
+    // If batch request fails, return error for all resourceIds. Capture the HTTP
+    // status from `BlockError` so fetch analytics can break failures down by
+    // statusCode (EDITOR-7862); undefined for non-HTTP failures.
     return blockNodeIdentifiers.map(blockNodeIdentifier => ({
       error: {
         type: error instanceof BlockError ? mapBlockError(error) : SyncBlockError.Errored,
-        reason: error.message
+        reason: error.message,
+        ...(error instanceof BlockError && {
+          statusCode: error.status
+        })
       },
       resourceId: blockNodeIdentifier.resourceId
     }));
@@ -458,10 +463,13 @@ class BlockServiceADFFetchProvider {
       };
     } catch (error) {
       if (error instanceof BlockError) {
+        // Capture the HTTP status so fetch analytics can break failures down by
+        // statusCode (EDITOR-7862).
         return {
           error: {
             type: mapBlockError(error),
-            reason: error.message
+            reason: error.message,
+            statusCode: error.status
           },
           resourceId
         };

package/dist/es2019/store-manager/referenceSyncBlockStoreManager.js

@@ -2,8 +2,8 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import isEqual from 'lodash/isEqual';
 import { logException } from '@atlaskit/editor-common/monitoring';
 import { fg } from '@atlaskit/platform-feature-flags';
-import { SyncBlockError } from '../common/types';
-import { buildErrorAttribution, cacheDeletionForcedPayload, fetchErrorPayload, fetchSuccessPayload, getSourceInfoErrorPayload, sourceInfoOrphanedPayload, updateReferenceErrorPayload } from '../utils/errorHandling';
+import { isProviderNotReadyError, ProviderNotReadyError, SyncBlockError } from '../common/types';
+import { buildErrorAttribution, buildFetchErrorAttribution, cacheDeletionForcedPayload, fetchErrorPayload, fetchSuccessPayload, getSourceInfoErrorPayload, sourceInfoOrphanedPayload, updateReferenceErrorPayload } from '../utils/errorHandling';
 import { getFetchExperience, getFetchSourceInfoExperience, getSaveReferenceExperience } from '../utils/experienceTracking';
 import { resolveSyncBlockInstance } from '../utils/resolveSyncBlockInstance';
 import { createSyncBlockNode, getSourceProductFromResourceIdSafe, normalizeSyncBlockJSONContent } from '../utils/utils';
@@ -79,7 +79,9 @@ export class ReferenceSyncBlockStoreManager {
     this._batchFetcher = new SyncBlockBatchFetcher({
       getSubscriptions: () => this._subscriptionManager.getSubscriptions(),
       fetchSyncBlocksData: nodes => this.fetchSyncBlocksData(nodes),
-      getFireAnalyticsEvent: () => this.fireAnalyticsEvent
+      getFireAnalyticsEvent: () => this.fireAnalyticsEvent,
+      // EDITOR-7860: skip + re-queue fetches while not ready / torn down.
+      isProviderReady: () => this.hasDataProvider()
     });
 
     // The provider might have SSR data cache already set, so we need to update the cache in session memory storage
@@ -89,6 +91,17 @@ export class ReferenceSyncBlockStoreManager {
     return node.type.name === 'syncBlock';
   }
 
+  /**
+   * Whether the async data provider is wired and the manager is not torn down.
+   * Consumers gate fetch/subscribe on this to avoid a false `Data provider not
+   * set` fetch error (EDITOR-7860). The `isDestroyed` check covers managers
+   * orphaned mid-flight during an async provider swap, where `dataProvider`
+   * alone is insufficient.
+   */
+  hasDataProvider() {
+    return !this.isDestroyed && !!this.dataProvider;
+  }
+
   /**
    * Enables or disables real-time GraphQL subscriptions for block updates.
    * When enabled, the store manager will subscribe to real-time updates
@@ -412,6 +425,11 @@ export class ReferenceSyncBlockStoreManager {
       return;
     }
     if (!this.dataProvider) {
+      // EDITOR-7860: tag the throw so catch sites can suppress the benign
+      // not-ready/torn-down case. Gate-off keeps the legacy throw + message.
+      if (fg('platform_editor_blocks_patch_3')) {
+        throw new ProviderNotReadyError();
+      }
       throw new Error('Data provider not set');
     }
     nodesToFetch.forEach(node => {
@@ -454,10 +472,12 @@ export class ReferenceSyncBlockStoreManager {
     data.forEach(syncBlockInstance => {
       var _resolvedSyncBlockIns;
       if (!syncBlockInstance.resourceId) {
-        var _syncBlockInstance$er, _syncBlockInstance$er2, _this$fireAnalyticsEv8;
+        var _syncBlockInstance$er, _syncBlockInstance$er2, _this$fireAnalyticsEv8, _syncBlockInstance$er3, _syncBlockInstance$er4, _syncBlockInstance$er5;
         const payload = ((_syncBlockInstance$er = syncBlockInstance.error) === null || _syncBlockInstance$er === void 0 ? void 0 : _syncBlockInstance$er.reason) || ((_syncBlockInstance$er2 = syncBlockInstance.error) === null || _syncBlockInstance$er2 === void 0 ? void 0 : _syncBlockInstance$er2.type) || 'Returned sync block instance does not have resource id';
         // No resourceId means we cannot derive a sourceProduct here; intentionally omit.
-        (_this$fireAnalyticsEv8 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv8 === void 0 ? void 0 : _this$fireAnalyticsEv8.call(this, fetchErrorPayload(payload));
+        // Classify on the structured `type` first, falling back to the free-text
+        // `reason`/payload (EDITOR-7862).
+        (_this$fireAnalyticsEv8 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv8 === void 0 ? void 0 : _this$fireAnalyticsEv8.call(this, fetchErrorPayload(payload, undefined, undefined, buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), ((_syncBlockInstance$er3 = syncBlockInstance.error) === null || _syncBlockInstance$er3 === void 0 ? void 0 : _syncBlockInstance$er3.type) || ((_syncBlockInstance$er4 = syncBlockInstance.error) === null || _syncBlockInstance$er4 === void 0 ? void 0 : _syncBlockInstance$er4.reason) || payload, (_syncBlockInstance$er5 = syncBlockInstance.error) === null || _syncBlockInstance$er5 === void 0 ? void 0 : _syncBlockInstance$er5.statusCode)));
         return;
       }
       const existingSyncBlock = this.getFromCache(syncBlockInstance.resourceId);
@@ -491,7 +511,10 @@ export class ReferenceSyncBlockStoreManager {
         const isRetryingEntityNotFound = syncBlockInstance.error.type === SyncBlockError.EntityNotFound && ((_this$entityNotFoundR = this.entityNotFoundRetryCount.get(syncBlockInstance.resourceId)) !== null && _this$entityNotFoundR !== void 0 ? _this$entityNotFoundR : 0) < ENTITY_NOT_FOUND_MAX_RETRIES && fg('platform_synced_block_patch_13');
         if (!isRetryingEntityNotFound) {
           var _this$fireAnalyticsEv9, _syncBlockInstance$da, _syncBlockInstance$da2;
-          (_this$fireAnalyticsEv9 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv9 === void 0 ? void 0 : _this$fireAnalyticsEv9.call(this, fetchErrorPayload(syncBlockInstance.error.reason || syncBlockInstance.error.type, syncBlockInstance.resourceId, (_syncBlockInstance$da = (_syncBlockInstance$da2 = syncBlockInstance.data) === null || _syncBlockInstance$da2 === void 0 ? void 0 : _syncBlockInstance$da2.product) !== null && _syncBlockInstance$da !== void 0 ? _syncBlockInstance$da : getSourceProductFromResourceIdSafe(syncBlockInstance.resourceId)));
+          // Classify on the structured `type` (a `SyncBlockError` enum value) first,
+          // falling back to the free-text `reason` so source-state/permission strings
+          // are still bucketed (EDITOR-7862). The emitted `error` attribute is unchanged.
+          (_this$fireAnalyticsEv9 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv9 === void 0 ? void 0 : _this$fireAnalyticsEv9.call(this, fetchErrorPayload(syncBlockInstance.error.reason || syncBlockInstance.error.type, syncBlockInstance.resourceId, (_syncBlockInstance$da = (_syncBlockInstance$da2 = syncBlockInstance.data) === null || _syncBlockInstance$da2 === void 0 ? void 0 : _syncBlockInstance$da2.product) !== null && _syncBlockInstance$da !== void 0 ? _syncBlockInstance$da : getSourceProductFromResourceIdSafe(syncBlockInstance.resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), syncBlockInstance.error.type || syncBlockInstance.error.reason, syncBlockInstance.error.statusCode)));
         }
         if (syncBlockInstance.error.type === SyncBlockError.NotFound || syncBlockInstance.error.type === SyncBlockError.Forbidden) {
           hasExpectedError = true;
@@ -779,10 +802,16 @@ export class ReferenceSyncBlockStoreManager {
       return this._subscriptionManager.subscribeToSyncBlock(resourceId, localId, callback);
     } catch (error) {
       var _this$fireAnalyticsEv11;
+      // EDITOR-7860: benign not-ready/torn-down case — suppress both the
+      // exception-tracker log and the analytics event (checked first so the
+      // benign case stays fully silent). Gate-off behaviour is unchanged.
+      if (isProviderNotReadyError(error) && fg('platform_editor_blocks_patch_3')) {
+        return () => {};
+      }
       logException(error, {
         location: 'editor-synced-block-provider/referenceSyncBlockStoreManager'
       });
-      (_this$fireAnalyticsEv11 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv11 === void 0 ? void 0 : _this$fireAnalyticsEv11.call(this, fetchErrorPayload(error.message));
+      (_this$fireAnalyticsEv11 = this.fireAnalyticsEvent) === null || _this$fireAnalyticsEv11 === void 0 ? void 0 : _this$fireAnalyticsEv11.call(this, fetchErrorPayload(error.message, undefined, undefined, buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), error.message)));
       return () => {};
     }
   }

package/dist/es2019/store-manager/syncBlockBatchFetcher.js

@@ -1,7 +1,9 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import rafSchedule from 'raf-schd';
 import { logException } from '@atlaskit/editor-common/monitoring';
-import { fetchErrorPayload } from '../utils/errorHandling';
+import { fg } from '@atlaskit/platform-feature-flags';
+import { isProviderNotReadyError } from '../common/types';
+import { buildFetchErrorAttribution, fetchErrorPayload } from '../utils/errorHandling';
 import { createSyncBlockNode, getSourceProductFromResourceIdSafe } from '../utils/utils';
 /**
  * Handles debounced batch-fetching of sync block data via `raf-schd`.
@@ -21,6 +23,17 @@ export class SyncBlockBatchFetcher {
       if (this.pendingFetchRequests.size === 0) {
         return;
       }
+
+      // EDITOR-7860: not ready — skip and leave resourceIds queued for the
+      // next batch once the provider resolves. Gate-off is unchanged (the
+      // readiness check is nested under the gate so it is not consulted when
+      // the gate is off, and `fg()` stays a standalone condition so gate
+      // exposure is still tracked — satisfies @atlaskit/platform/no-preconditioning).
+      if (fg('platform_editor_blocks_patch_3')) {
+        if (this.deps.isProviderReady && !this.deps.isProviderReady()) {
+          return;
+        }
+      }
       const resourceIds = Array.from(this.pendingFetchRequests);
       const syncBlockNodes = resourceIds.map(resId => {
         const subscriptions = this.deps.getSubscriptions().get(resId) || {};
@@ -32,12 +45,25 @@ export class SyncBlockBatchFetcher {
       // Track in-flight before the fetch so guards remain positive.
       resourceIds.forEach(resId => this.inFlightFetches.add(resId));
       this.deps.fetchSyncBlocksData(syncBlockNodes).catch(error => {
+        // EDITOR-7860: benign not-ready throw — re-queue for retry and emit
+        // nothing (no analytics, no exception-tracker noise). Checked before
+        // `logException` so the benign case stays silent. Re-schedule so the
+        // re-queued IDs are retried on the next frame even if no further
+        // `queueFetch()` arrives. Gate-off behaviour is unchanged.
+        if (isProviderNotReadyError(error) && fg('platform_editor_blocks_patch_3')) {
+          resourceIds.forEach(resId => this.pendingFetchRequests.add(resId));
+          if (!this.isDestroyed) {
+            this.scheduledBatchFetch();
+          }
+          return;
+        }
         logException(error, {
           location: 'editor-synced-block-provider/syncBlockBatchFetcher/batchedFetchSyncBlocks'
         });
+        const attribution = buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), error.message);
         resourceIds.forEach(resId => {
           var _this$deps$getFireAna;
-          (_this$deps$getFireAna = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna === void 0 ? void 0 : _this$deps$getFireAna(fetchErrorPayload(error.message, resId, getSourceProductFromResourceIdSafe(resId)));
+          (_this$deps$getFireAna = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna === void 0 ? void 0 : _this$deps$getFireAna(fetchErrorPayload(error.message, resId, getSourceProductFromResourceIdSafe(resId), attribution));
         });
       }).finally(() => {
         // If the fetcher was destroyed while the request was in flight,

package/dist/es2019/store-manager/syncBlockProviderFactoryManager.js

@@ -1,7 +1,8 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import { logException } from '@atlaskit/editor-common/monitoring';
 import { ProviderFactory } from '@atlaskit/editor-common/provider-factory';
-import { fetchErrorPayload } from '../utils/errorHandling';
+import { fg } from '@atlaskit/platform-feature-flags';
+import { buildFetchErrorAttribution, fetchErrorPayload } from '../utils/errorHandling';
 import { parseResourceId } from '../utils/resourceId';
 import { getSourceProductFromResourceIdSafe } from '../utils/utils';
 /**
@@ -21,7 +22,7 @@ export class SyncBlockProviderFactoryManager {
       logException(error, {
         location: 'editor-synced-block-provider/syncBlockProviderFactoryManager'
       });
-      (_this$deps$getFireAna = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna === void 0 ? void 0 : _this$deps$getFireAna(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId)));
+      (_this$deps$getFireAna = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna === void 0 ? void 0 : _this$deps$getFireAna(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), error.message)));
       return undefined;
     }
     const {
@@ -55,7 +56,7 @@ export class SyncBlockProviderFactoryManager {
         logException(error, {
           location: 'editor-synced-block-provider/syncBlockProviderFactoryManager'
         });
-        (_this$deps$getFireAna2 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna2 === void 0 ? void 0 : _this$deps$getFireAna2(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId)));
+        (_this$deps$getFireAna2 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna2 === void 0 ? void 0 : _this$deps$getFireAna2(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), error.message)));
       }
     }
     return providerFactory;
@@ -133,7 +134,7 @@ export class SyncBlockProviderFactoryManager {
     if (!syncBlock.data.sourceAri || !syncBlock.data.product) {
       var _this$deps$getFireAna3, _syncBlock$data$produ;
       (_this$deps$getFireAna3 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna3 === void 0 ? void 0 : _this$deps$getFireAna3(fetchErrorPayload('Sync block source ari or product not found', resourceId, // Prefer cached product when available; fall back to parsing resourceId.
-      (_syncBlock$data$produ = syncBlock.data.product) !== null && _syncBlock$data$produ !== void 0 ? _syncBlock$data$produ : getSourceProductFromResourceIdSafe(resourceId)));
+      (_syncBlock$data$produ = syncBlock.data.product) !== null && _syncBlock$data$produ !== void 0 ? _syncBlock$data$produ : getSourceProductFromResourceIdSafe(resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), 'Sync block source ari or product not found')));
       return;
     }
     const parentInfo = dataProvider.retrieveSyncBlockParentInfo(syncBlock.data.sourceAri, syncBlock.data.product);

package/dist/es2019/store-manager/syncBlockSubscriptionManager.js

@@ -1,7 +1,7 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import { logException } from '@atlaskit/editor-common/monitoring';
 import { fg } from '@atlaskit/platform-feature-flags';
-import { fetchErrorPayload, fetchSuccessPayload } from '../utils/errorHandling';
+import { buildFetchErrorAttribution, fetchErrorPayload, fetchSuccessPayload } from '../utils/errorHandling';
 import { resolveSyncBlockInstance } from '../utils/resolveSyncBlockInstance';
 import { getSourceProductFromResourceIdSafe } from '../utils/utils';
 /**
@@ -87,7 +87,7 @@ export class SyncBlockSubscriptionManager {
         logException(error, {
           location: 'editor-synced-block-provider/syncBlockSubscriptionManager/notifySubscriptionChangeListeners'
         });
-        (_this$deps$getFireAna = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna === void 0 ? void 0 : _this$deps$getFireAna(fetchErrorPayload(error.message));
+        (_this$deps$getFireAna = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna === void 0 ? void 0 : _this$deps$getFireAna(fetchErrorPayload(error.message, undefined, undefined, buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), error.message)));
       }
     });
   }
@@ -264,6 +264,9 @@ export class SyncBlockSubscriptionManager {
       // recovers on reconnect, so under the gate we don't fire a
       // user-facing error here — it's only surfaced on exhaustion (see
       // scheduleReconnection). Gate OFF keeps the legacy fire-on-drop.
+      // This branch only runs when the gate is OFF, so buildFetchErrorAttribution
+      // would return undefined; the structured attribution (EDITOR-7862) is therefore
+      // applied at the gate-ON exhaustion site in scheduleReconnection instead.
       if (!fg('platform_editor_blocks_patch_3')) {
         var _this$deps$getFireAna2;
         (_this$deps$getFireAna2 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna2 === void 0 ? void 0 : _this$deps$getFireAna2(fetchErrorPayload(error.message, resourceId, getSourceProductFromResourceIdSafe(resourceId)));
@@ -310,7 +313,7 @@ export class SyncBlockSubscriptionManager {
       logException(new Error(errorMessage), {
         location: 'editor-synced-block-provider/syncBlockSubscriptionManager/max-retries-exhausted'
       });
-      (_this$deps$getFireAna3 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna3 === void 0 ? void 0 : _this$deps$getFireAna3(fetchErrorPayload(errorMessage, resourceId, getSourceProductFromResourceIdSafe(resourceId)));
+      (_this$deps$getFireAna3 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna3 === void 0 ? void 0 : _this$deps$getFireAna3(fetchErrorPayload(errorMessage, resourceId, getSourceProductFromResourceIdSafe(resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), errorMessage)));
       return;
     }
     const delay = this.getReconnectionDelay(attempts);
@@ -409,9 +412,13 @@ export class SyncBlockSubscriptionManager {
       });
       this.deps.fetchSyncBlockSourceInfo(resolved.resourceId);
     } else {
-      var _syncBlockInstance$er, _syncBlockInstance$er2, _this$deps$getFireAna5, _syncBlockInstance$da3, _syncBlockInstance$da4;
+      var _syncBlockInstance$er, _syncBlockInstance$er2, _this$deps$getFireAna5, _syncBlockInstance$da3, _syncBlockInstance$da4, _syncBlockInstance$er3, _syncBlockInstance$er4, _syncBlockInstance$er5;
       const errorMessage = ((_syncBlockInstance$er = syncBlockInstance.error) === null || _syncBlockInstance$er === void 0 ? void 0 : _syncBlockInstance$er.reason) || ((_syncBlockInstance$er2 = syncBlockInstance.error) === null || _syncBlockInstance$er2 === void 0 ? void 0 : _syncBlockInstance$er2.type);
-      (_this$deps$getFireAna5 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna5 === void 0 ? void 0 : _this$deps$getFireAna5(fetchErrorPayload(errorMessage, syncBlockInstance.resourceId, (_syncBlockInstance$da3 = (_syncBlockInstance$da4 = syncBlockInstance.data) === null || _syncBlockInstance$da4 === void 0 ? void 0 : _syncBlockInstance$da4.product) !== null && _syncBlockInstance$da3 !== void 0 ? _syncBlockInstance$da3 : getSourceProductFromResourceIdSafe(syncBlockInstance.resourceId)));
+
+      // Prefer the structured `type` (a `SyncBlockError` enum value) for classification
+      // and fall back to the free-text `reason` so source-state/permission strings are
+      // still bucketed (EDITOR-7862). The emitted free-text `error` attribute is unchanged.
+      (_this$deps$getFireAna5 = this.deps.getFireAnalyticsEvent()) === null || _this$deps$getFireAna5 === void 0 ? void 0 : _this$deps$getFireAna5(fetchErrorPayload(errorMessage, syncBlockInstance.resourceId, (_syncBlockInstance$da3 = (_syncBlockInstance$da4 = syncBlockInstance.data) === null || _syncBlockInstance$da4 === void 0 ? void 0 : _syncBlockInstance$da4.product) !== null && _syncBlockInstance$da3 !== void 0 ? _syncBlockInstance$da3 : getSourceProductFromResourceIdSafe(syncBlockInstance.resourceId), buildFetchErrorAttribution(fg('platform_editor_blocks_patch_3'), ((_syncBlockInstance$er3 = syncBlockInstance.error) === null || _syncBlockInstance$er3 === void 0 ? void 0 : _syncBlockInstance$er3.type) || ((_syncBlockInstance$er4 = syncBlockInstance.error) === null || _syncBlockInstance$er4 === void 0 ? void 0 : _syncBlockInstance$er4.reason), (_syncBlockInstance$er5 = syncBlockInstance.error) === null || _syncBlockInstance$er5 === void 0 ? void 0 : _syncBlockInstance$er5.statusCode)));
     }
   }
 }