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

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@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.0",
   "description": "Tokowaka Client for SpaceCat - Edge optimization config management",
   "type": "module",
   "engines": {

package/src/index.js

@@ -50,6 +50,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 +89,7 @@ class TokowakaClient {
     const {
       TOKOWAKA_SITE_CONFIG_BUCKET: bucketName,
       TOKOWAKA_PREVIEW_BUCKET: previewBucketName,
+      IMPORT_WORKER_QUEUE_URL: importWorkerQueueUrl,
     } = env;
 
     if (context.tokowakaClient) {
@@ -100,6 +102,8 @@ class TokowakaClient {
       s3Client: s3?.s3Client ?? context.s3Client,
       env,
       dataAccess: context.dataAccess,
+      sqs: context.sqs,
+      importWorkerQueueUrl,
     }, log);
     context.tokowakaClient = client;
     return client;
@@ -114,10 +118,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 +141,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 +1086,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 +1520,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 +1533,7 @@ class TokowakaClient {
     allSuggestions,
     updatedBy,
     coveredSuggestions,
+    siteId,
   ) {
     const data = suggestion.getData();
     const coverageField = data?.isDomainWide ? 'coveredByDomainWide' : 'coveredByPattern';
@@ -1586,7 +1604,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 +1704,7 @@ class TokowakaClient {
             allSuggestions,
             updatedBy,
             coveredSuggestions,
+            site.getId(),
           );
           deployedPatternSuggestions.push(suggestion);
         } catch (error) {

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}`);

package/test/index.test.js

@@ -3197,6 +3197,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 +3291,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 +6064,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 +6597,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');
+      }
+    });
   });
 });