@adobe/spacecat-shared-tokowaka-client 1.20.0 → 1.21.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-tokowaka-client-v1.21.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.21.0...@adobe/spacecat-shared-tokowaka-client-v1.21.1) (2026-07-15)
+
+### Bug Fixes
+
+* utility for marking suggestions as covered ([#1810](https://github.com/adobe/spacecat-shared/issues/1810)) ([2709d47](https://github.com/adobe/spacecat-shared/commit/2709d4741bfe2968dfb481ceedf3e283525f5e71))
+
+## [@adobe/spacecat-shared-tokowaka-client-v1.21.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.20.0...@adobe/spacecat-shared-tokowaka-client-v1.21.0) (2026-07-14)
+
+### Features
+
+* **tokowaka-client:** offload covered-marking saves to import worker queue above threshold ([#1802](https://github.com/adobe/spacecat-shared/issues/1802)) ([ad1fe43](https://github.com/adobe/spacecat-shared/commit/ad1fe433b4628c38ef0d2d4f4008c2932b5981e0))
+
 ## [@adobe/spacecat-shared-tokowaka-client-v1.20.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-tokowaka-client-v1.19.1...@adobe/spacecat-shared-tokowaka-client-v1.20.0) (2026-06-27)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-tokowaka-client",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {

package/src/index.js

@@ -27,7 +27,6 @@ import {
 } from './utils/s3-utils.js';
 import {
   omitKeys,
-  isEdgeDeployableSuggestionStatus,
   isPatternSuggestion,
   groupSuggestionsByUrlPath,
   filterEligibleSuggestions,
@@ -36,8 +35,8 @@ import {
   cleanupCoveredSuggestions,
   classifySuggestions,
   filterBatchCoveredSuggestions,
+  findCoveredSuggestions,
 } from './utils/suggestion-utils.js';
-import { buildUrlMatcher } from './utils/pattern-utils.js';
 import { getEffectiveBaseURL } from './utils/site-utils.js';
 import { removePatternFromMetaconfig, addPatternsToMetaconfig } from './utils/metaconfig-utils.js';
 import { fetchHtmlWithWarmup, calculateForwardedHost } from './utils/custom-html-utils.js';
@@ -50,6 +49,7 @@ import {
 
 export { FastlyKVClient } from './fastly-kv-client.js';
 export { calculateForwardedHost } from './utils/custom-html-utils.js';
+export { SUGGESTION_BULK_UPDATE_TYPE } from './utils/suggestion-utils.js';
 
 // CloudFront control-plane (free functions + constants).
 export {
@@ -88,6 +88,7 @@ class TokowakaClient {
     const {
       TOKOWAKA_SITE_CONFIG_BUCKET: bucketName,
       TOKOWAKA_PREVIEW_BUCKET: previewBucketName,
+      IMPORT_WORKER_QUEUE_URL: importWorkerQueueUrl,
     } = env;
 
     if (context.tokowakaClient) {
@@ -100,6 +101,8 @@ class TokowakaClient {
       s3Client: s3?.s3Client ?? context.s3Client,
       env,
       dataAccess: context.dataAccess,
+      sqs: context.sqs,
+      importWorkerQueueUrl,
     }, log);
     context.tokowakaClient = client;
     return client;
@@ -114,10 +117,13 @@ class TokowakaClient {
    * @param {Object} config.env - Environment variables (for CDN credentials)
    * @param {Object} [config.dataAccess] - Data access layer
    *   (provides Suggestion.saveMany for batch saves)
+   * @param {Object} [config.sqs] - SQS client (sendMessage(queueUrl, payload)). Used to offload
+   *   very large covered-suggestion saves to the import worker instead of saving them directly.
+   * @param {string} [config.importWorkerQueueUrl] - Import worker SQS queue URL.
    * @param {Object} log - Logger instance
    */
   constructor({
-    bucketName, previewBucketName, s3Client, env = {}, dataAccess,
+    bucketName, previewBucketName, s3Client, env = {}, dataAccess, sqs, importWorkerQueueUrl,
   }, log) {
     this.log = log;
 
@@ -134,6 +140,8 @@ class TokowakaClient {
     this.s3Client = s3Client;
     this.env = env;
     this.dataAccess = dataAccess;
+    this.sqs = sqs;
+    this.importWorkerQueueUrl = importWorkerQueueUrl;
 
     this.mapperRegistry = new MapperRegistry(log);
     this.cdnClientRegistry = new CdnClientRegistry(env, log);
@@ -1077,7 +1085,14 @@ class TokowakaClient {
             this.log.info(`[edge-rollback] Cleaning ${covered.length} covered suggestion(s) for pattern ${suggestion.getId()} (isDomainWide=${isDomainWide}, fallback=${coveredFallback})`);
           }
           // eslint-disable-next-line no-await-in-loop, max-len
-          await cleanupCoveredSuggestions(this.dataAccess, covered, coveredFallback, updatedBy, fieldsToStrip, this.log);
+          await cleanupCoveredSuggestions(this.dataAccess, covered, coveredFallback, updatedBy, fieldsToStrip, this.log, {
+            sqs: this.sqs,
+            queueUrl: this.importWorkerQueueUrl,
+            siteId: site.getId(),
+            unset: fieldsToStrip,
+            updatedBy: updatedBy ?? coveredFallback,
+            log: this.log,
+          });
         }
       }
     }
@@ -1504,6 +1519,7 @@ class TokowakaClient {
    * @param {Array} allSuggestions - Full opportunity suggestion list
    * @param {string} updatedBy
    * @param {Array} coveredSuggestions - Accumulator (mutated)
+   * @param {string} siteId
    * @returns {Promise<void>} Throws on metaconfig upload failure
    * @private
    */
@@ -1516,6 +1532,7 @@ class TokowakaClient {
     allSuggestions,
     updatedBy,
     coveredSuggestions,
+    siteId,
   ) {
     const data = suggestion.getData();
     const coverageField = data?.isDomainWide ? 'coveredByDomainWide' : 'coveredByPattern';
@@ -1541,41 +1558,13 @@ class TokowakaClient {
     suggestion.setUpdatedBy(updatedBy);
     // suggestion.save() is deferred — caller batches saves via saveSuggestions.
 
-    // Mark per-URL suggestions covered by this pattern.
-    const matchers = allowedRegexPatterns.flatMap((p) => {
-      const m = buildUrlMatcher(p);
-      if (!m) {
-        // eslint-disable-next-line max-len
-        this.log.warn(`[edge-deploy] Pattern '${p}' for suggestion ${suggestion.getId()} is invalid, skipping`);
-      }
-      return m ? [m] : [];
-    });
-
-    if (matchers.length === 0) {
-      return;
-    }
-
-    const covered = allSuggestions.filter((s) => {
-      if (s.getId() === suggestion.getId()) {
-        return false;
-      }
-      if (skippedInBatchIds.has(s.getId())) {
-        return false;
-      }
-      if (!isEdgeDeployableSuggestionStatus(s.getStatus())) {
-        return false;
-      }
-      if (s.getData()?.edgeDeployed) {
-        return false;
-      }
-      // Path-level pattern suggestions (not domain-wide) are fully covered by a
-      // domain-wide deployment. Other pattern suggestions (including other DW ones) are not.
-      if (isPatternSuggestion(s)) {
-        return coverageField === 'coveredByDomainWide' && !s.getData()?.isDomainWide;
-      }
-      const url = s.getData()?.url;
-      return url && matchers.some((match) => match(url));
-    });
+    const covered = findCoveredSuggestions(
+      suggestion,
+      allowedRegexPatterns,
+      allSuggestions,
+      skippedInBatchIds,
+      this.log,
+    );
 
     // eslint-disable-next-line max-len
     this.log.info(`[edge-deploy] Pattern ${suggestion.getId()}: found ${covered.length} coverable per-URL suggestions (field=${coverageField})`);
@@ -1586,7 +1575,14 @@ class TokowakaClient {
         cs.setUpdatedBy(updatedBy);
       });
       try {
-        await saveSuggestions(this.dataAccess, covered);
+        await saveSuggestions(this.dataAccess, covered, {
+          sqs: this.sqs,
+          queueUrl: this.importWorkerQueueUrl,
+          siteId,
+          set: { [coverageField]: suggestion.getId() },
+          updatedBy,
+          log: this.log,
+        });
         coveredSuggestions.push(...covered);
         // eslint-disable-next-line max-len
         this.log.info(`[edge-deploy] Marked ${covered.length} suggestions as ${coverageField}=${suggestion.getId()}`);
@@ -1679,6 +1675,7 @@ class TokowakaClient {
             allSuggestions,
             updatedBy,
             coveredSuggestions,
+            site.getId(),
           );
           deployedPatternSuggestions.push(suggestion);
         } catch (error) {
@@ -1733,6 +1730,64 @@ class TokowakaClient {
     return { succeededSuggestions, failedSuggestions, coveredSuggestions };
   }
 
+  /**
+   * Finds and marks the suggestions that fall within a pattern suggestion's
+   * scope (domain-wide or segment/path) as covered and saves them.
+   *
+   * @param {Object} patternSuggestion - The domain-wide / segment pattern suggestion
+   * @param {Array} allSuggestions - Full opportunity suggestion list to search for matches
+   * @param {string} siteId - Site ID
+   * @param {string} [updatedBy]
+   * @returns {Promise<Array>} the marked suggestions
+   */
+  async markPatternCoveredSuggestions(
+    patternSuggestion,
+    allSuggestions,
+    siteId,
+    updatedBy = 'edge-deploy',
+  ) {
+    const allowedRegexPatterns = patternSuggestion.getData()?.allowedRegexPatterns;
+    if (!Array.isArray(allowedRegexPatterns) || allowedRegexPatterns.length === 0) {
+      this.log.warn(`[edge-deploy] Pattern suggestion ${patternSuggestion.getId()} has `
+      + 'no allowedRegexPatterns, skipping cover-marking');
+      return [];
+    }
+    const covered = findCoveredSuggestions(
+      patternSuggestion,
+      allowedRegexPatterns,
+      allSuggestions,
+      new Set(),
+      this.log,
+    );
+    if (covered.length === 0) {
+      return [];
+    }
+    const coverageField = patternSuggestion.getData()?.isDomainWide
+      ? 'coveredByDomainWide' : 'coveredByPattern';
+    covered.forEach((s) => {
+      s.setData({ ...s.getData(), [coverageField]: patternSuggestion.getId() });
+      s.setUpdatedBy(updatedBy);
+    });
+    try {
+      await saveSuggestions(this.dataAccess, covered, {
+        sqs: this.sqs,
+        queueUrl: this.importWorkerQueueUrl,
+        siteId,
+        set: { [coverageField]: patternSuggestion.getId() },
+        updatedBy,
+        log: this.log,
+      });
+      this.log.info(`[edge-deploy] Marked ${covered.length} suggestions as ${coverageField}=${patternSuggestion.getId()}`);
+      return covered;
+    } catch (saveError) {
+      this.log.warn(
+        '[edge-deploy] Failed to mark covered suggestions for pattern suggestion '
+        + `${patternSuggestion.getId()}: ${saveError.message}`,
+      );
+      return [];
+    }
+  }
+
   /**
    * Strips the `applyStale` flag from patches in S3 for the given per-URL suggestions.
    * Called when an experiment completes so edge reverts to normal (non-stale) behaviour.

package/src/utils/suggestion-utils.js

@@ -92,26 +92,68 @@ export function filterEligibleSuggestions(suggestions, mapper) {
   return { eligible, ineligible };
 }
 
+// Import worker job type for a bulk suggestion field update (agnostic set/unset by id).
+export const SUGGESTION_BULK_UPDATE_TYPE = 'suggestion-bulk-update';
+
 /**
  * Batch-saves suggestions using the optimal strategy based on count.
  *
  * - <= 1700: sequential chunked upsert via saveMany (chunkSize 25).
  *   ~4s for 1700 suggestions from the DB layer, but ~11s observed end-to-end
  *   from the API due to serialization, network, and Lambda overhead.
- * - > 1700: parallel individual .save() via Promise.allSettled to avoid
- *   sequential chunk bottleneck at scale.
+ * - > 1700 with no queueContext: parallel individual .save() via Promise.allSettled to
+ *   avoid sequential chunk bottleneck at scale.
+ * - > 1700 with queueContext: enqueues a SUGGESTION_BULK_UPDATE_TYPE job to the import
+ *   worker instead of saving here (the worker fetches by id and applies
+ *   queueContext.set/unset itself). Falls back to the Promise.allSettled path above
+ *   if sqs/queueUrl aren't configured or sendMessage fails, so a queue outage
+ *   degrades rather than silently drops the save.
  *
  * @param {Object} dataAccess - Data access layer
  * @param {Array} suggestions - Suggestion entities to save
+ * @param {Object} [queueContext] - sqs, queueUrl, siteId, set/unset,
+ *   updatedBy (already resolved), log
  * @returns {Promise<void>}
  */
 const PARALLEL_SAVE_THRESHOLD = 1700;
 
-export async function saveSuggestions(dataAccess, suggestions) {
+export async function saveSuggestions(dataAccess, suggestions, queueContext) {
   if (suggestions.length === 0) {
     return;
   }
   if (suggestions.length > PARALLEL_SAVE_THRESHOLD) {
+    if (queueContext) {
+      const {
+        sqs, queueUrl, siteId, set, unset, updatedBy, log,
+      } = queueContext;
+
+      if (queueUrl && sqs) {
+        try {
+          await sqs.sendMessage(queueUrl, {
+            type: SUGGESTION_BULK_UPDATE_TYPE,
+            siteId,
+            suggestionIds: suggestions.map((s) => s.getId()),
+            ...(set && { set }),
+            ...(unset && { unset }),
+            updatedBy,
+          });
+          log.info(
+            `[suggestion-bulk-update] Queued bulk update for ${suggestions.length} suggestion(s)`,
+          );
+          return;
+        } catch (error) {
+          log.error(
+            `[suggestion-bulk-update] Failed to queue bulk update, falling back to direct save: ${error.message}`,
+          );
+        }
+      } else {
+        log.warn(
+          '[suggestion-bulk-update] SQS/IMPORT_WORKER_QUEUE_URL not configured; '
+          + `falling back to direct save for ${suggestions.length} suggestion(s)`,
+        );
+      }
+    }
+
     const results = await Promise.allSettled(suggestions.map((s) => s.save()));
     const failed = results.filter((r) => r.status === 'rejected');
     if (failed.length > 0) {
@@ -150,10 +192,11 @@ export function stripSuggestion(suggestion, actorFallback, updatedBy) {
  * @param {string|undefined} updatedBy - Explicit actor
  * @param {string[]} fieldsToStrip - Specific fields to remove
  * @param {Object} log - Logger instance
+ * @param {Object} [queueContext] - Passed through to saveSuggestions unchanged
  * @returns {Promise<void>}
  */
 // eslint-disable-next-line max-len
-export async function cleanupCoveredSuggestions(dataAccess, covered, actorFallback, updatedBy, fieldsToStrip, log) {
+export async function cleanupCoveredSuggestions(dataAccess, covered, actorFallback, updatedBy, fieldsToStrip, log, queueContext) {
   if (covered.length === 0) {
     return;
   }
@@ -162,7 +205,7 @@ export async function cleanupCoveredSuggestions(dataAccess, covered, actorFallba
     cs.setUpdatedBy(updatedBy ?? actorFallback);
   });
   try {
-    await saveSuggestions(dataAccess, covered);
+    await saveSuggestions(dataAccess, covered, queueContext);
   } catch (error) {
     // eslint-disable-next-line max-len
     log.error(`[edge-rollback-failed] Failed to clean ${covered.length} covered suggestion(s): ${error.message}`);
@@ -241,3 +284,58 @@ export function filterBatchCoveredSuggestions(validSuggestions, patternSuggestio
 
   return { remaining, skippedInBatch };
 }
+
+/**
+ * Finds the suggestions in `allSuggestions` that are covered by a pattern suggestion's
+ * allowedRegexPatterns
+ *
+ * @param {Object} patternSuggestion - The domain-wide / segment pattern suggestion
+ * @param {Array<string>} allowedRegexPatterns
+ * @param {Array} allSuggestions - Full opportunity suggestion list to search
+ * @param {Set<string>} [excludeIds] - Suggestion IDs to skip (e.g. already handled in-batch)
+ * @param {Object} log - Logger instance
+ * @returns {Array} Suggestions covered by the pattern
+ */
+export function findCoveredSuggestions(
+  patternSuggestion,
+  allowedRegexPatterns,
+  allSuggestions,
+  excludeIds,
+  log,
+) {
+  const isDomainWide = patternSuggestion.getData()?.isDomainWide === true;
+  const matchers = allowedRegexPatterns.flatMap((p) => {
+    const m = buildUrlMatcher(p);
+    if (!m) {
+      // eslint-disable-next-line max-len
+      log.warn(`[edge-deploy] Pattern '${p}' for suggestion ${patternSuggestion.getId()} is invalid, skipping`);
+    }
+    return m ? [m] : [];
+  });
+
+  if (matchers.length === 0) {
+    return [];
+  }
+
+  return allSuggestions.filter((s) => {
+    if (s.getId() === patternSuggestion.getId()) {
+      return false;
+    }
+    if (excludeIds?.has(s.getId())) {
+      return false;
+    }
+    if (!isEdgeDeployableSuggestionStatus(s.getStatus())) {
+      return false;
+    }
+    if (s.getData()?.edgeDeployed) {
+      return false;
+    }
+    // Path-level pattern suggestions (not domain-wide) are fully covered by a
+    // domain-wide deployment. Other pattern suggestions (including other DW ones) are not.
+    if (isPatternSuggestion(s)) {
+      return isDomainWide && !s.getData()?.isDomainWide;
+    }
+    const url = s.getData()?.url;
+    return url && matchers.some((match) => match(url));
+  });
+}

package/test/index.test.js

@@ -147,6 +147,98 @@ describe('TokowakaClient', () => {
     });
   });
 
+  describe('markPatternCoveredSuggestions', () => {
+    const mkPattern = (isDomainWide) => ({
+      getId: () => (isDomainWide ? 'dw-1' : 'path-1'),
+      getData: () => (isDomainWide
+        ? { isDomainWide: true, allowedRegexPatterns: ['/*'] }
+        : { allowedRegexPatterns: ['/foo/*'] }),
+    });
+    const mkCovered = (id, url = `https://example.com/foo/${id}`) => ({
+      getId: () => id,
+      getStatus: () => 'NEW',
+      getData: () => ({ url }),
+      setData: sinon.stub(),
+      setUpdatedBy: sinon.stub(),
+      save: sinon.stub().resolves(),
+    });
+
+    it('marks all matching suggestions in the opportunity with coveredByDomainWide', async () => {
+      const covered = [mkCovered('a'), mkCovered('b')];
+
+      const result = await client.markPatternCoveredSuggestions(
+        mkPattern(true),
+        covered,
+        'site-1',
+        'tester',
+      );
+
+      expect(result).to.deep.equal(covered);
+      covered.forEach((s) => {
+        expect(s.setData.calledWithMatch({ coveredByDomainWide: 'dw-1' })).to.be.true;
+        expect(s.setUpdatedBy.calledOnceWith('tester')).to.be.true;
+      });
+      expect(client.dataAccess.Suggestion.saveMany.calledOnceWith(covered)).to.be.true;
+    });
+
+    it('marks only URLs matching the segment/path pattern with coveredByPattern', async () => {
+      const matching = mkCovered('a', 'https://example.com/foo/a');
+      const nonMatching = mkCovered('b', 'https://example.com/bar/b');
+
+      const result = await client.markPatternCoveredSuggestions(
+        mkPattern(false),
+        [matching, nonMatching],
+        'site-1',
+      );
+
+      expect(result).to.deep.equal([matching]);
+      expect(matching.setData.calledWithMatch({ coveredByPattern: 'path-1' })).to.be.true;
+      expect(matching.setUpdatedBy.calledOnceWith('edge-deploy')).to.be.true;
+      expect(nonMatching.setData.called).to.be.false;
+    });
+
+    it('is a no-op when the pattern suggestion has no allowedRegexPatterns', async () => {
+      const noPattern = { getId: () => 'dw-1', getData: () => ({ isDomainWide: true }) };
+
+      expect(await client.markPatternCoveredSuggestions(noPattern, [mkCovered('a')], 'site-1'))
+        .to.deep.equal([]);
+      expect(client.dataAccess.Suggestion.saveMany.called).to.be.false;
+    });
+
+    it('is a no-op when nothing in allSuggestions matches', async () => {
+      const result = await client.markPatternCoveredSuggestions(mkPattern(true), [], 'site-1');
+
+      expect(result).to.deep.equal([]);
+      expect(client.dataAccess.Suggestion.saveMany.called).to.be.false;
+    });
+
+    it('enqueues a bulk-update job with the passed-in siteId when covered count is large', async () => {
+      const covered = Array.from({ length: 1701 }, (_, i) => mkCovered(`c${i}`));
+      client.sqs = { sendMessage: sinon.stub().resolves() };
+      client.importWorkerQueueUrl = 'https://sqs.test/import-worker-queue';
+
+      await client.markPatternCoveredSuggestions(mkPattern(true), covered, 'site-1', 'tester');
+
+      expect(client.sqs.sendMessage).to.have.been.calledOnce;
+      const [queueUrl, payload] = client.sqs.sendMessage.firstCall.args;
+      expect(queueUrl).to.equal('https://sqs.test/import-worker-queue');
+      expect(payload).to.include({ type: 'suggestion-bulk-update', siteId: 'site-1' });
+      expect(payload.set).to.deep.equal({ coveredByDomainWide: 'dw-1' });
+      expect(payload.updatedBy).to.equal('tester');
+      expect(client.dataAccess.Suggestion.saveMany.called).to.be.false;
+    });
+
+    it('warns and returns [] instead of throwing when saveSuggestions fails', async () => {
+      client.dataAccess.Suggestion.saveMany.rejects(new Error('DB down'));
+      const covered = [mkCovered('a')];
+
+      const result = await client.markPatternCoveredSuggestions(mkPattern(true), covered, 'site-1');
+
+      expect(result).to.deep.equal([]);
+      expect(client.log.warn.calledWithMatch(/Failed to mark covered suggestions/)).to.be.true;
+    });
+  });
+
   describe('createFrom', () => {
     it('should create client from context', () => {
       const context = {
@@ -3197,6 +3289,57 @@ describe('TokowakaClient', () => {
       );
     });
 
+    it('enqueues a suggestion-bulk-update job instead of saveMany when cleaning up more than the threshold (domain-wide rollback)', async () => {
+      const prerenderOpportunity = { getId: () => 'opp-dw', getType: () => 'prerender' };
+      const dwSuggestion = {
+        getId: () => 'dw-1',
+        getData: () => ({
+          isDomainWide: true,
+          allowedRegexPatterns: ['/*'],
+          edgeDeployed: Date.now(),
+        }),
+        setData: sinon.stub(),
+        setUpdatedBy: sinon.stub(),
+        save: sinon.stub().resolves(),
+      };
+      const covered = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `covered-${i}`,
+        getData: () => ({ url: `https://example.com/page${i}`, coveredByDomainWide: 'dw-1' }),
+        setData: sinon.stub(),
+        setUpdatedBy: sinon.stub(),
+        save: sinon.stub().resolves(),
+      }));
+
+      sinon.stub(client, 'fetchMetaconfig').resolves({
+        siteId: 'site-123',
+        prerender: { allowList: ['/*'] },
+      });
+      sinon.stub(client, 'uploadMetaconfig').resolves();
+      client.sqs = { sendMessage: sinon.stub().resolves() };
+      client.importWorkerQueueUrl = 'https://sqs.test/import-worker-queue';
+
+      await client.rollbackSuggestions(
+        mockSite,
+        prerenderOpportunity,
+        [dwSuggestion],
+        { allSuggestions: [dwSuggestion, ...covered], updatedBy: 'test@example.com' },
+      );
+
+      expect(client.sqs.sendMessage).to.have.been.calledOnce;
+      const [queueUrl, payload] = client.sqs.sendMessage.firstCall.args;
+      expect(queueUrl).to.equal('https://sqs.test/import-worker-queue');
+      expect(payload).to.include({ type: 'suggestion-bulk-update', siteId: 'site-123' });
+      expect(payload).to.not.have.property('opportunityId');
+      expect(payload.suggestionIds).to.have.length(1701);
+      expect(payload.unset).to.deep.equal(['coveredByDomainWide']);
+      expect(payload.updatedBy).to.equal('test@example.com');
+      // Not saved directly — the enqueue replaces the saveMany call for this batch.
+      expect(client.dataAccess.Suggestion.saveMany).to.not.have.been.calledWith(
+        sinon.match((arr) => arr.length === 1701),
+        sinon.match.any,
+      );
+    });
+
     it('cleans up covered suggestions (coveredByPattern) when rolling back a path-level pattern', async () => {
       const prerenderOpportunity = { getId: () => 'opp-p', getType: () => 'prerender' };
       const pathSuggestion = {
@@ -3240,6 +3383,54 @@ describe('TokowakaClient', () => {
       expect(coveredData).to.not.have.property('coveredByPattern');
     });
 
+    it('enqueues a suggestion-bulk-update job instead of saveMany when cleaning up more than the threshold (path-level rollback)', async () => {
+      const prerenderOpportunity = { getId: () => 'opp-p', getType: () => 'prerender' };
+      const pathSuggestion = {
+        getId: () => 'path-1',
+        getData: () => ({
+          allowedRegexPatterns: ['/products/*'],
+          edgeDeployed: Date.now(),
+        }),
+        setData: sinon.stub(),
+        setUpdatedBy: sinon.stub(),
+        save: sinon.stub().resolves(),
+      };
+      const covered = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `covered-${i}`,
+        getData: () => ({
+          url: `https://example.com/products/item-${i}`,
+          edgeDeployed: Date.now(),
+          coveredByPattern: 'path-1',
+        }),
+        setData: sinon.stub(),
+        setUpdatedBy: sinon.stub(),
+        save: sinon.stub().resolves(),
+      }));
+
+      sinon.stub(client, 'fetchMetaconfig').resolves({
+        siteId: 'site-123',
+        prerender: { allowList: ['/products/*'] },
+      });
+      sinon.stub(client, 'uploadMetaconfig').resolves();
+      client.sqs = { sendMessage: sinon.stub().resolves() };
+      client.importWorkerQueueUrl = 'https://sqs.test/import-worker-queue';
+
+      await client.rollbackSuggestions(
+        mockSite,
+        prerenderOpportunity,
+        [pathSuggestion],
+        { allSuggestions: [pathSuggestion, ...covered] },
+      );
+
+      expect(client.sqs.sendMessage).to.have.been.calledOnce;
+      const [queueUrl, payload] = client.sqs.sendMessage.firstCall.args;
+      expect(queueUrl).to.equal('https://sqs.test/import-worker-queue');
+      expect(payload).to.include({ type: 'suggestion-bulk-update', siteId: 'site-123' });
+      expect(payload).to.not.have.property('opportunityId');
+      expect(payload.suggestionIds).to.have.length(1701);
+      expect(payload.unset).to.deep.equal(['edgeDeployed', 'tokowakaDeployed', 'coveredByPattern']);
+    });
+
     it('uses domain-wide-rollback fallback for covered suggestions when updatedBy is not provided (domain-wide parent)', async () => {
       const prerenderOpportunity = { getId: () => 'opp-dw', getType: () => 'prerender' };
       const dwSuggestion = {
@@ -5965,6 +6156,37 @@ describe('TokowakaClient', () => {
       expect(covered.getData()).to.have.property('coveredByDomainWide', 'dw1');
     });
 
+    it('enqueues a suggestion-bulk-update job instead of saveMany when covered count exceeds the threshold (domain-wide)', async () => {
+      const dw = makeSuggestion('dw1', {
+        isDomainWide: true,
+        allowedRegexPatterns: ['^https://example\\.com/.*'],
+      });
+      const covered = Array.from({ length: 1701 }, (_, i) => makeSuggestion(
+        `covered-${i}`,
+        { url: `https://example.com/page${i}` },
+      ));
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+      client.sqs = { sendMessage: sinon.stub().resolves() };
+      client.importWorkerQueueUrl = 'https://sqs.test/import-worker-queue';
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [dw],
+        allSuggestions: [dw, ...covered],
+      });
+
+      expect(result.coveredSuggestions).to.have.length(1701);
+      expect(client.sqs.sendMessage).to.have.been.calledOnce;
+      const [queueUrl, payload] = client.sqs.sendMessage.firstCall.args;
+      expect(queueUrl).to.equal('https://sqs.test/import-worker-queue');
+      expect(payload).to.include({ type: 'suggestion-bulk-update', siteId: 'site-123' });
+      expect(payload).to.not.have.property('opportunityId');
+      expect(payload.suggestionIds).to.have.length(1701);
+      expect(payload.set).to.deep.equal({ coveredByDomainWide: 'dw1' });
+    });
+
     it('should not mark already-domain-wide suggestions as covered', async () => {
       const dw1 = makeSuggestion('dw1', {
         isDomainWide: true,
@@ -6467,6 +6689,36 @@ describe('TokowakaClient', () => {
       expect(result.coveredSuggestions).to.not.include(urlElsewhere);
     });
 
+    it('enqueues a suggestion-bulk-update job instead of saveMany when covered count exceeds the threshold (path-level)', async () => {
+      const path = makeSuggestion('p1', {
+        allowedRegexPatterns: ['/products/*'],
+      });
+      const covered = Array.from({ length: 1701 }, (_, i) => makeSuggestion(
+        `covered-${i}`,
+        { url: `https://example.com/products/item-${i}` },
+      ));
+
+      fetchMetaconfigStub.resolves({ siteId: 'site-123' });
+      client.sqs = { sendMessage: sinon.stub().resolves() };
+      client.importWorkerQueueUrl = 'https://sqs.test/import-worker-queue';
+
+      const result = await client.deployToEdge({
+        site: mockSite,
+        opportunity: mockOpportunity,
+        targetSuggestions: [path],
+        allSuggestions: [path, ...covered],
+      });
+
+      expect(result.coveredSuggestions).to.have.length(1701);
+      expect(client.sqs.sendMessage).to.have.been.calledOnce;
+      const [queueUrl, payload] = client.sqs.sendMessage.firstCall.args;
+      expect(queueUrl).to.equal('https://sqs.test/import-worker-queue');
+      expect(payload).to.include({ type: 'suggestion-bulk-update', siteId: 'site-123' });
+      expect(payload).to.not.have.property('opportunityId');
+      expect(payload.suggestionIds).to.have.length(1701);
+      expect(payload.set).to.deep.equal({ coveredByPattern: 'p1' });
+    });
+
     it('path deploy marks as failed with statusCode 500 when metaconfig upload fails', async () => {
       const path = makeSuggestion('p1', {
         allowedRegexPatterns: ['/products/*'],

package/test/utils/suggestion-utils.test.js

@@ -12,7 +12,12 @@
 
 import { expect } from 'chai';
 import sinon from 'sinon';
-import { groupSuggestionsByUrlPath, filterEligibleSuggestions, saveSuggestions } from '../../src/utils/suggestion-utils.js';
+import {
+  groupSuggestionsByUrlPath,
+  filterEligibleSuggestions,
+  saveSuggestions,
+  SUGGESTION_BULK_UPDATE_TYPE,
+} from '../../src/utils/suggestion-utils.js';
 
 describe('Suggestion Utils', () => {
   describe('groupSuggestionsByUrlPath', () => {
@@ -223,5 +228,153 @@ describe('Suggestion Utils', () => {
         expect(error.message).to.include('DB error');
       }
     });
+
+    it('should enqueue a bulk update job instead of saving when queueContext is provided', async () => {
+      const dataAccess = { Suggestion: { saveMany: sinon.stub() } };
+      const items = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `sugg-${i}`,
+        save: sinon.stub().resolves(),
+      }));
+      const queueContext = {
+        sqs: { sendMessage: sinon.stub().resolves() },
+        queueUrl: 'https://sqs.example.com/queue',
+        siteId: 'site-1',
+        set: { coveredByDomainWide: 'pattern-sugg-id' },
+        updatedBy: 'system',
+        log: { warn: sinon.stub(), info: sinon.stub(), error: sinon.stub() },
+      };
+
+      await saveSuggestions(dataAccess, items, queueContext);
+
+      expect(dataAccess.Suggestion.saveMany.called).to.be.false;
+      expect(items[0].save.called).to.be.false;
+      expect(queueContext.sqs.sendMessage.calledOnce).to.be.true;
+      const [queueUrl, payload] = queueContext.sqs.sendMessage.firstCall.args;
+      expect(queueUrl).to.equal('https://sqs.example.com/queue');
+      expect(payload).to.deep.equal({
+        type: SUGGESTION_BULK_UPDATE_TYPE,
+        siteId: 'site-1',
+        suggestionIds: items.map((s) => s.getId()),
+        set: { coveredByDomainWide: 'pattern-sugg-id' },
+        updatedBy: 'system',
+      });
+      expect(queueContext.log.info.calledOnce).to.be.true;
+    });
+
+    it('should include unset instead of set when queueContext.unset is provided', async () => {
+      const dataAccess = { Suggestion: { saveMany: sinon.stub() } };
+      const items = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `sugg-${i}`,
+        save: sinon.stub().resolves(),
+      }));
+      const queueContext = {
+        sqs: { sendMessage: sinon.stub().resolves() },
+        queueUrl: 'https://sqs.example.com/queue',
+        siteId: 'site-1',
+        unset: ['coveredByDomainWide'],
+        updatedBy: 'system',
+        log: { warn: sinon.stub(), info: sinon.stub(), error: sinon.stub() },
+      };
+
+      await saveSuggestions(dataAccess, items, queueContext);
+
+      const [, payload] = queueContext.sqs.sendMessage.firstCall.args;
+      expect(payload.set).to.be.undefined;
+      expect(payload.unset).to.deep.equal(['coveredByDomainWide']);
+    });
+
+    it('falls back to direct save when queueUrl is not configured', async () => {
+      const dataAccess = { Suggestion: { saveMany: sinon.stub() } };
+      const items = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `sugg-${i}`,
+        save: sinon.stub().resolves(),
+      }));
+      const queueContext = {
+        sqs: { sendMessage: sinon.stub().resolves() },
+        queueUrl: undefined,
+        siteId: 'site-1',
+        updatedBy: 'system',
+        log: { warn: sinon.stub(), info: sinon.stub(), error: sinon.stub() },
+      };
+
+      await saveSuggestions(dataAccess, items, queueContext);
+
+      expect(queueContext.sqs.sendMessage.called).to.be.false;
+      expect(queueContext.log.warn.calledOnce).to.be.true;
+      expect(queueContext.log.warn.firstCall.args[0]).to.include('SQS/IMPORT_WORKER_QUEUE_URL not configured');
+      expect(items[0].save.calledOnce).to.be.true;
+      expect(items[1700].save.calledOnce).to.be.true;
+      expect(dataAccess.Suggestion.saveMany.called).to.be.false;
+    });
+
+    it('falls back to direct save when sqs is not configured', async () => {
+      const dataAccess = { Suggestion: { saveMany: sinon.stub() } };
+      const items = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `sugg-${i}`,
+        save: sinon.stub().resolves(),
+      }));
+      const queueContext = {
+        sqs: undefined,
+        queueUrl: 'https://sqs.example.com/queue',
+        siteId: 'site-1',
+        updatedBy: 'system',
+        log: { warn: sinon.stub(), info: sinon.stub(), error: sinon.stub() },
+      };
+
+      await saveSuggestions(dataAccess, items, queueContext);
+
+      expect(queueContext.log.warn.calledOnce).to.be.true;
+      expect(queueContext.log.warn.firstCall.args[0]).to.include('SQS/IMPORT_WORKER_QUEUE_URL not configured');
+      expect(items[0].save.calledOnce).to.be.true;
+    });
+
+    it('falls back to direct save when sqs.sendMessage rejects', async () => {
+      const dataAccess = { Suggestion: { saveMany: sinon.stub() } };
+      const items = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `sugg-${i}`,
+        save: sinon.stub().resolves(),
+      }));
+      const queueContext = {
+        sqs: { sendMessage: sinon.stub().rejects(new Error('SQS unavailable')) },
+        queueUrl: 'https://sqs.example.com/queue',
+        siteId: 'site-1',
+        updatedBy: 'system',
+        log: { warn: sinon.stub(), info: sinon.stub(), error: sinon.stub() },
+      };
+
+      await saveSuggestions(dataAccess, items, queueContext);
+
+      expect(queueContext.log.error.calledOnce).to.be.true;
+      expect(queueContext.log.error.firstCall.args[0]).to.include('Failed to queue bulk update');
+      expect(queueContext.log.error.firstCall.args[0]).to.include('SQS unavailable');
+      expect(items[0].save.calledOnce).to.be.true;
+      expect(items[1700].save.calledOnce).to.be.true;
+      expect(dataAccess.Suggestion.saveMany.called).to.be.false;
+    });
+
+    it('throws when the direct-save fallback also fails after a queue failure', async () => {
+      const dataAccess = { Suggestion: { saveMany: sinon.stub() } };
+      const items = Array.from({ length: 1701 }, (_, i) => ({
+        getId: () => `sugg-${i}`,
+        save: i === 0
+          ? sinon.stub().rejects(new Error('DB error'))
+          : sinon.stub().resolves(),
+      }));
+      const queueContext = {
+        sqs: { sendMessage: sinon.stub().rejects(new Error('SQS unavailable')) },
+        queueUrl: 'https://sqs.example.com/queue',
+        siteId: 'site-1',
+        updatedBy: 'system',
+        log: { warn: sinon.stub(), info: sinon.stub(), error: sinon.stub() },
+      };
+
+      try {
+        await saveSuggestions(dataAccess, items, queueContext);
+        expect.fail('should have thrown');
+      } catch (error) {
+        expect(error.message).to.include('1 of 1701 suggestions failed');
+        expect(error.message).to.include('DB error');
+      }
+    });
   });
 });