tango-app-api-audit 3.6.53 → 3.6.55

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-audit",
-    "version": "3.6.53",
+    "version": "3.6.55",
     "description": "audit & audit metrics apis",
     "main": "index.js",
     "type": "module",

package/scripts/verify-retrigger-lock.mjs

@@ -0,0 +1,115 @@
+/* eslint-disable no-console */
+/**
+ * Standalone verification for the reTrigger idempotency lock.
+ *
+ *   node scripts/verify-retrigger-lock.mjs
+ *
+ * Connects to the configured (non-prod) Mongo, exercises the lock under a
+ * concurrent burst, and asserts the dedup / idempotency guarantees. Uses a
+ * throwaway, clearly-namespaced key and cleans up after itself.
+ */
+import mongoose from 'mongoose';
+import { connectdb } from '../config/database/database.js';
+import {
+  acquireReTriggerLock,
+  completeReTriggerLock,
+  releaseReTriggerLock,
+} from '../src/service/reTriggerLock.service.js';
+
+// Distinctive throwaway key - never collides with real audit data.
+const KEY = {
+  storeId: '__verify__-lock-99-999',
+  fileDate: '01-01-1970',
+  moduleType: 'traffic',
+  zoneName: 'traffic_zone',
+};
+const COLLECTION = 'reTriggerLock';
+
+let failures = 0;
+function assert( label, cond ) {
+  if ( cond ) {
+    console.log( `  PASS  ${label}` );
+  } else {
+    failures++;
+    console.error( `  FAIL  ${label}` );
+  }
+}
+
+function waitForConnection() {
+  if ( mongoose.connection.readyState === 1 ) return Promise.resolve();
+  return new Promise( ( resolve, reject ) => {
+    mongoose.connection.once( 'connected', resolve );
+    mongoose.connection.once( 'error', reject );
+  } );
+}
+
+async function cleanup() {
+  await mongoose.connection.collection( COLLECTION ).deleteMany( {
+    storeId: KEY.storeId,
+  } );
+}
+
+async function main() {
+  connectdb();
+  await waitForConnection();
+  console.log( 'Connected. Running verification...\n' );
+
+  await cleanup(); // start clean
+
+  // 1) Concurrent burst: exactly one caller may acquire.
+  console.log( '1) Concurrent burst of 25 identical requests' );
+  const burst = await Promise.all(
+      Array.from( { length: 25 }, () => acquireReTriggerLock( KEY ) ),
+  );
+  const acquired = burst.filter( ( r ) => r.acquired ).length;
+  assert( 'exactly ONE request acquires the lock', acquired === 1 );
+  assert(
+      'the other 24 are told it is in progress',
+      burst.filter( ( r ) => !r.acquired ).length === 24,
+  );
+  assert(
+      'losers see status "processing"',
+      burst.filter( ( r ) => !r.acquired )
+          .every( ( r ) => r.lock?.status === 'processing' ),
+  );
+
+  // 2) Completed combo: subsequent request reports "completed", does not acquire.
+  console.log( '\n2) After completion' );
+  await completeReTriggerLock( KEY );
+  const afterComplete = await acquireReTriggerLock( KEY );
+  assert( 'does not re-acquire a completed combo', afterComplete.acquired === false );
+  assert( 'reports status "completed"', afterComplete.lock?.status === 'completed' );
+
+  // 3) Release allows a fresh, legitimate retry.
+  console.log( '\n3) After release (failure path)' );
+  await releaseReTriggerLock( KEY );
+  const afterRelease = await acquireReTriggerLock( KEY );
+  assert( 'a released combo can be re-acquired', afterRelease.acquired === true );
+
+  // 4) Stale 'processing' lock is reclaimed (simulate a crashed prior attempt).
+  console.log( '\n4) Stale-lock reclaim' );
+  await mongoose.connection.collection( COLLECTION ).updateOne(
+      { storeId: KEY.storeId },
+      { $set: { status: 'processing', updatedAt: new Date( Date.now() - 10 * 60 * 1000 ) } },
+  );
+  const afterStale = await acquireReTriggerLock( KEY );
+  assert( 'a stale (>5m) processing lock is reclaimed', afterStale.acquired === true );
+
+  // 5) A fresh 'processing' lock is NOT reclaimable.
+  console.log( '\n5) Fresh lock is not reclaimable' );
+  const freshDup = await acquireReTriggerLock( KEY );
+  assert( 'a fresh processing lock blocks new acquirers', freshDup.acquired === false );
+
+  await cleanup();
+  console.log( failures === 0 ? '\nAll checks passed.' : `\n${failures} check(s) FAILED.` );
+}
+
+main()
+    .catch( ( err ) => {
+      console.error( '\nVerification crashed:', err );
+      failures++;
+    } )
+    .finally( async () => {
+      await mongoose.connection.close().catch( () => {} );
+      process.exit( failures === 0 ? 0 : 1 );
+    } );

package/src/controllers/audit.controllers.js

@@ -39,6 +39,11 @@ import {
   updateOneStoreAudit,
   updateManyStoreAudit,
 } from '../service/storeAudit.service.js';
+import {
+  acquireReTriggerLock,
+  completeReTriggerLock,
+  releaseReTriggerLock,
+} from '../service/reTriggerLock.service.js';
 import _ from 'lodash';
 import {
   createAuditLog,
@@ -68,7 +73,6 @@ import { aggregateTraxAuditData, findOneTraxAuditData } from '../service/traxAud
 import { bulkWriteAuditUserWallet, createAuditUserWallet, findOneAuditUserWallet } from '../service/auditUserWallet.service.js';
 import { updateOneAuditUsers } from '../service/auditUsers.service.js';
 import { bulkUpdate, clearScroll, upsertOpenSearchData, scrollResponse, searchOpenSearchData, updateOpenSearchData } from 'tango-app-api-middleware/src/utils/openSearch.js';
-
 // import { aggregateAuditUsers } from '../service/auditUsers.service.js';
 
 /*           < -- *** Configuration ***   -->      */
@@ -3631,9 +3635,37 @@ export async function overAllAuditSummary( req, res ) {
 }
 
 export async function reTrigger( req, res ) {
+  const inputData = req.body;
+  const lockKey = {
+    storeId: inputData.storeId,
+    fileDate: inputData.fileDate,
+    moduleType: inputData.moduleType,
+    zoneName: inputData.zoneName,
+  };
+  let lockAcquired = false;
   try {
+    // --- Idempotency gate ------------------------------------------------
+    // Atomically claim this (storeId, fileDate, moduleType, zoneName) combo.
+    // Under a burst of identical requests exactly one caller wins; the rest get
+    // the existing status back and skip re-processing - so no duplicate SQS
+    // messages / assignments are produced.
+    const { acquired, lock } = await acquireReTriggerLock( {
+      ...lockKey,
+      triggeredBy: req.user._id,
+      triggerType: inputData.triggerType,
+    } );
+    if ( !acquired ) {
+      return res.sendSuccess( {
+        result: lock?.status === 'completed' ?
+          'This file has already been Re-Triggered.' :
+          'A Re-Trigger for this file is already in progress.',
+        status: lock?.status || 'processing',
+        duplicate: true,
+      } );
+    }
+    lockAcquired = true;
+
     const openSearch = JSON.parse( process.env.OPENSEARCH );
-    const inputData = req.body;
     const sqs = JSON.parse( process.env.SQS );
     const query = {
       storeId: inputData.storeId,
@@ -3648,6 +3680,13 @@ export async function reTrigger( req, res ) {
     }
     switch ( inputData.triggerType ) {
       case 'queue':
+        // Only push to the queue when the store has not already been queued.
+        // A 'not_assign' status means a prior reTrigger already pushed this
+        // store - pushing again would create a duplicate queue message.
+        if ( req.audit.status === 'not_assign' ) {
+          await releaseReTriggerLock( lockKey );
+          return res.sendError( 'This store has already been pushed to the queue', 400 );
+        }
         const msg = {
           store_id: inputData.storeId,
           zone_id: inputData.zoneName,
@@ -3712,6 +3751,10 @@ export async function reTrigger( req, res ) {
         }
         break;
       case 'user':
+          if ( req.audit.status === 'not_assign' ) {
+          await releaseReTriggerLock( lockKey );
+          return res.sendError( 'This store has already assigned to the user', 400 );
+        }
         const assignUser = await findOneUser( { _id: new mongoose.Types.ObjectId( inputData.userId ) } );
         const assignUserRecord = {
           storeId: inputData.storeId,
@@ -3781,8 +3824,15 @@ export async function reTrigger( req, res ) {
 
 
     await updateOpenSearchData( openSearch.trackerInput, `${inputData.storeId}_${inputData.fileDate}_23:00`, { doc: updateQuery } );
+    // Processing + SQS send succeeded - mark the lock completed so any later
+    // identical request returns the existing status instead of re-triggering.
+    await completeReTriggerLock( lockKey );
     return res.sendSuccess( { result: 'The File has been Re-Triggered Succesfully' } );
   } catch ( error ) {
+    // Release the lock on failure so a legitimate retry can re-acquire it.
+    if ( lockAcquired ) {
+      await releaseReTriggerLock( lockKey ).catch( () => {} );
+    }
     const err = error.message;
     logger.error( { error: error, message: req.body, function: 'reTrigger' } );
     return res.sendError( err, 500 );
@@ -5814,5 +5864,3 @@ export async function rePushAuditStores( req, res ) {
     return res.sendError( err, 500 );
   }
 }
-
-

package/src/controllers/eyeTestAudit.controllers.js

@@ -1414,6 +1414,7 @@ export async function summaryList( req, res ) {
     if ( inputData.clientId !== '11' ) {
       return res.sendError( 'No data found', 204 );
     }
+
     // declare openSearch and get data form the .env/secret manager
     const openSearch = JSON.parse( process.env.OPENSEARCH );
 
@@ -1763,7 +1764,6 @@ export async function summaryList( req, res ) {
         } );
       }
       const getcount = await aggregateClusters( inputData.keyType === 'rm'?RMQuery: clusterQuery );
-
       const count = getcount?.length || 0;
       if ( count == 0 ) {
         return res.sendError( 'No data', 204 );
@@ -1787,7 +1787,6 @@ export async function summaryList( req, res ) {
         );
       }
       const getCluster = await aggregateClusters( inputData.keyType === 'rm'?RMQuery: clusterQuery );
-      logger.info( { masg: '...........getCluster', getCluster, RMQuery } );
       if ( !getCluster || getCluster?.length == 0 ) {
         return res.sendError( 'No data', 204 );
       }
@@ -3175,175 +3174,3 @@ export async function updateEmailConfig1( req, res ) {
     return res.sendError( err, 500 );
   }
 }
-
-export async function getConversationDetails( req, res ) {
-  try {
-    const inputData = req.params;
-
-    // Query OpenSearch audio_analytics_report index by doc_id and moduleType
-    const query = {
-      'query': {
-        'bool': {
-          'must': [
-            {
-              'term': {
-                'unique_id.keyword': inputData.id,
-              },
-            },
-          ],
-        },
-      },
-      'size': 1,
-    };
-
-    const result = await getOpenSearchData( 'audio_analytics_report_v2', query );
-    if ( result?.body?.hits?.hits?.length === 0 ) {
-      return res.sendError( 'No data found', 204 );
-    }
-
-    const source = result?.body?.hits?.hits[0]?._source;
-
-    if ( !source ) {
-      return res.sendError( 'No data found', 204 );
-    }
-
-    // Helper function to format duration: convert seconds to mm:ss format
-    const formatDuration = ( seconds ) => {
-      if ( !seconds || seconds === 0 ) return '0:00';
-      const minutes = Math.floor( seconds / 60 );
-      const secs = Math.floor( seconds % 60 );
-      return `${minutes}:${secs.toString().padStart( 2, '0' )}`;
-    };
-
-    // Helper: parse "s3://bucket/path/to/file" into { Bucket, file_path }
-    const parseS3Uri = ( uri ) => {
-      if ( !uri ) return null;
-      const withoutScheme = uri.replace( /^s3:\/\//, '' );
-      const slashIdx = withoutScheme.indexOf( '/' );
-      if ( slashIdx === -1 ) return null;
-      return {
-        Bucket: withoutScheme.slice( 0, slashIdx ),
-        file_path: withoutScheme.slice( slashIdx + 1 ),
-      };
-    };
-
-    // Helper function to format transcript: fetch and clean transcript file
-    const getFormattedTranscript = async ( transcriptPath ) => {
-      try {
-        if ( !transcriptPath ) return '';
-
-        const s3Parts = parseS3Uri( transcriptPath );
-        logger.info( { s3Parts: s3Parts, function: 'getFormattedTranscript' } );
-        if ( !s3Parts ) return '';
-
-        const transcriptSignedUrl = await signedUrl( { ...s3Parts, key: 'aws' } );
-        if ( !transcriptSignedUrl ) return '';
-
-        const fetchRes = await fetch( transcriptSignedUrl );
-        if ( !fetchRes.ok ) return '';
-        let text = await fetchRes.text();
-
-        // Remove timestamps like [00:00:33.954 --> 00:00:36.154]
-        text = text.replace( /\[\d{2}:\d{2}:\d{2}\.\d{3} --> \d{2}:\d{2}:\d{2}\.\d{3}\]\s*/g, '' );
-
-        // Remove [silence] markers
-        text = text.replace( /\[silence\]\s*/g, '' );
-
-        // Replace multiple newlines with single space to create paragraphs
-        text = text.replace( /\n+/g, ' ' );
-
-        // Clean up multiple spaces
-        text = text.replace( /\s+/g, ' ' ).trim();
-
-        return text;
-      } catch ( error ) {
-        logger.error( { message: error, function: 'getFormattedTranscript' } );
-        return '';
-      }
-    };
-
-    // Helper function to format metric names
-    const formatMetricName = ( name ) => {
-      const nameMap = {
-        'Torchlight Exam': 'Torchlight Check',
-        'JCC': 'JCC Check',
-        'Distance Visual Acuity': 'Distance-VA-Check',
-        'Duochrome': 'Duochrome Check',
-        'Near Visual Acuity': 'Near Addition Check',
-      };
-      return nameMap[name] || name;
-    };
-
-    // Format metrics results with sequential time allocation
-    const matchedCohort = source?.cohort_analysis_results?.find( ( c ) => c.cohortId === 'cohort_11_1ddea945-ff3a-4c11-95a9-bb425ca927de' );
-    const metricsData = matchedCohort?.metrics_results || [];
-
-    // Calculate sequential times for detected metrics
-    let currentSeconds = 0;
-    const totalDuration = Math.floor( source?.duration || 1200 );
-    const detectedCount = metricsData.filter( ( m ) => m.contextsEvaluated?.[0]?.isDetected ).length || 1;
-    const secondsPerMetric = Math.floor( totalDuration / Math.max( detectedCount, 1 ) );
-
-    const formattedMetrics = metricsData.map( ( metric, index ) => {
-      const isDetected = metric.contextsEvaluated?.[0]?.isDetected;
-
-      let startTime = '';
-      let endTime = '';
-
-      if ( isDetected ) {
-        const startSeconds = currentSeconds;
-        const endSeconds = Math.min( currentSeconds + secondsPerMetric, totalDuration );
-
-        startTime = formatDuration( startSeconds );
-        endTime = formatDuration( endSeconds );
-
-        currentSeconds = endSeconds;
-      }
-
-      return {
-        metricId: metric.metricId,
-        metricName: formatMetricName( metric.metricName ),
-        metricType: metric.metricType,
-        status: metric.contextsEvaluated?.[0]?.isDetected === false ? 'fail':'pass',
-        contextsEvaluated: metric.contextsEvaluated?.[0]?.isDetected,
-        startTime: startTime,
-        endTime: endTime,
-        evidence_quote: metric.contextsEvaluated?.[0]?.isDetected === false ? '' : metric.evidence_quote,
-      };
-    } ) || [];
-
-    // Fetch signed URL for audio
-    const audioS3Parts = parseS3Uri( source?.s3_audio_path );
-    const audioSignedUrl = audioS3Parts ? await signedUrl( { ...audioS3Parts, key: 'aws' } ) : null;
-    // Fetch and format transcript
-    const formattedTranscript = await getFormattedTranscript( source?.s3_transcript_path );
-
-    // Get executive summary
-    // const executiveSummary = source?.cohort_analysis_results?.[0]?.executive_summary || {};
-
-    const response = {
-      doc_id: source?.doc_id,
-      // storeName: source?.storeName,
-      // storeID: source?.storeID,
-      // staffID: source?.staffID,
-      // state: source?.state,
-      // moduleType: source?.moduleType,
-      // fileDate: source?.filedate,
-      // processTimestamp: source?.processTimestamp,
-      duration: formatDuration( source?.duration ),
-      audio_url: audioSignedUrl,
-      // s3_transcript_path: source?.s3_transcript_path,
-      transcript_summary: formattedTranscript,
-      // overall_score: executiveSummary?.overall_score,
-      // conversation_summary: executiveSummary?.conversation_summary,
-      // key_pointers: executiveSummary?.key_pointers,
-      metrics_results: formattedMetrics,
-    };
-
-    return res.sendSuccess( { result: response } );
-  } catch ( error ) {
-    const err = error.message || 'Internal Server Error';
-    logger.error( { message: error, data: req.params, function: 'eyetestAudit-controller-getConversationDetails' } );
-    return res.sendError( err, 500 );
-  }
-}

package/src/dtos/audit.dtos.js

@@ -321,5 +321,3 @@ export const rePushAuditStoresSchema = joi.object( {
 export const rePushAuditStoresValid = {
   body: rePushAuditStoresSchema,
 };
-
-

package/src/dtos/eyeTestAudit.dtos.js

@@ -418,14 +418,3 @@ export const getEmailConfigSchema = joi.object( {
 export const getEmailConfigValid = {
   query: getEmailConfigSchema,
 };
-
-export const getConversationDetailsSchema = joi.object( {
-  id: joi.string().required().messages( {
-    'any.required': 'ID is required',
-    'string.empty': 'ID cannot be empty',
-  } ),
-} );
-
-export const getConversationDetailsValid = {
-  params: getConversationDetailsSchema,
-};

package/src/routes/audit.routes.js

@@ -45,10 +45,7 @@ auditRouter.get( '/get-user-audit-count-mtd', isAllowedSessionHandler, getUserAu
 
 // audit log
 auditRouter.get( '/audit-view-logs', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ] } ), validate( auditViewLogValid ), auditViewLogs );
-
-
 export default auditRouter;
 
 //
 auditRouter.post( '/re-push-audit-stores', validate( rePushAuditStoresValid ), rePushAuditStores );
-

package/src/routes/eyeTestAudit.routes.js

@@ -1,8 +1,8 @@
 import { Router } from 'express';
 import { isAllowedSessionHandler, validate } from 'tango-app-api-middleware';
 import { accessVerification } from 'tango-app-api-middleware';
-import { cancelValid, clusterListValid, emailAlertLogValid, getConversationDetailsValid, getEmailConfigValid, getFileHistoryValid, getFileValid, getListValid, getUserConfigValid, rmListValid, saveValid, summaryCardValid, summaryListValid, updateEmailConfigValid, updateUserConfigValid, userAuditedDataValid, viewFileValid } from '../dtos/eyeTestAudit.dtos.js';
-import { addUserConfig, cancel, clusterList, emailAlertLog, getConversationDetails, getEmailConfig, getFile, getFileHistory, getList, getUserConfig, rmList, save, summaryCard, summaryList, updateEmailConfig, updateEmailConfig1, updateUserConfig, userAuditedData, viewFile } from '../controllers/eyeTestAudit.controllers.js';
+import { cancelValid, clusterListValid, emailAlertLogValid, getEmailConfigValid, getFileHistoryValid, getFileValid, getListValid, getUserConfigValid, rmListValid, saveValid, summaryCardValid, summaryListValid, updateEmailConfigValid, updateUserConfigValid, userAuditedDataValid, viewFileValid } from '../dtos/eyeTestAudit.dtos.js';
+import { addUserConfig, cancel, clusterList, emailAlertLog, getEmailConfig, getFile, getFileHistory, getList, getUserConfig, rmList, save, summaryCard, summaryList, updateEmailConfig, updateEmailConfig1, updateUserConfig, userAuditedData, viewFile } from '../controllers/eyeTestAudit.controllers.js';
 import { isSuperAdmin, roleValidation, sendAlert } from '../validation/eyeTest.validation.js';
 
 export const eyeTestAuditRouter = Router();
@@ -15,10 +15,6 @@ eyeTestAuditRouter.post( '/cancel', isAllowedSessionHandler, accessVerification(
 eyeTestAuditRouter.get( '/get-file-history/:id/:type', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ] } ), validate( getFileHistoryValid ), getFileHistory );
 eyeTestAuditRouter.get( '/user-audited-data/:id', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ] } ), validate( userAuditedDataValid ), userAuditedData );
 
-// enhancement of march of 2026
-
-eyeTestAuditRouter.get( '/get-conversation-details/:id', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ] } ), validate( getConversationDetailsValid ), getConversationDetails );
-
 // enhancement of aug of 2025
 
 eyeTestAuditRouter.post( '/summary-list', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ] } ), validate( summaryListValid ), roleValidation, summaryList );

package/src/service/reTriggerLock.service.js

@@ -0,0 +1,129 @@
+import mongoose from 'mongoose';
+import { logger } from 'tango-app-api-middleware';
+
+/**
+ * Short-lived dedup / lock record for the reTrigger API.
+ *
+ * The UNIQUE compound index below is the atomic gate that makes reTrigger
+ * idempotent and thread-safe: under a burst of concurrent identical requests
+ * only ONE insert succeeds, every other insert fails with duplicate-key error
+ * E11000. MongoDB enforces this at the storage engine level, so it works across
+ * processes / pods - unlike an in-memory map or a non-atomic OpenSearch read.
+ */
+const reTriggerLockSchema = new mongoose.Schema(
+    {
+      storeId: { type: String, required: true },
+      fileDate: { type: String, required: true },
+      moduleType: { type: String, required: true },
+      // zoneName is part of the processing identity (different zones of the same
+      // store/date are distinct runs). Including it makes the gate MORE precise
+      // while still fully deduping an identical payload.
+      zoneName: { type: String, default: '' },
+      status: {
+        type: String,
+        enum: [ 'processing', 'completed' ],
+        default: 'processing',
+      },
+      triggeredBy: { type: mongoose.Schema.Types.ObjectId },
+      triggerType: { type: String },
+    },
+    { timestamps: true, strict: true, versionKey: false },
+);
+
+// Hard, atomic dedup gate.
+reTriggerLockSchema.index(
+    { storeId: 1, fileDate: 1, moduleType: 1, zoneName: 1 },
+    { unique: true },
+);
+// Keep the collection bounded. A 7-day window is far longer than any duplicate
+// burst, yet lets the same store/date be re-triggered in a later cycle.
+reTriggerLockSchema.index( { updatedAt: 1 }, { expireAfterSeconds: 7 * 24 * 60 * 60 } );
+
+const reTriggerLockModel = mongoose.model(
+    'reTriggerLock',
+    reTriggerLockSchema,
+    'reTriggerLock',
+);
+
+// Ensure the unique index physically exists even if mongoose autoIndex is
+// disabled in production - without it the atomic guarantee would be lost.
+// We keep the promise: acquire() awaits it so a cold-start burst can never slip
+// through before the index has finished building.
+const indexReady = reTriggerLockModel.createIndexes().catch( ( error ) => {
+  logger.error( { error, function: 'reTriggerLock.createIndexes' } );
+} );
+
+// A 'processing' lock older than this is treated as abandoned (crashed / timed
+// out request) and may be reclaimed so a legitimate retry is never blocked.
+const STALE_LOCK_MS = 5 * 60 * 1000;
+
+function buildKey( { storeId, fileDate, moduleType, zoneName } ) {
+  return { storeId, fileDate, moduleType, zoneName: zoneName || '' };
+}
+
+// Atomically try to acquire the reTrigger lock for a combo.
+// Returns { acquired: true, lock } for exactly one caller in a concurrent burst.
+// Returns { acquired: false, lock } for everyone else - `lock` carries the
+// existing status so the caller can report it instead of re-processing.
+export async function acquireReTriggerLock( payload ) {
+  // Guarantee the unique index is built before we rely on it as the dedup gate.
+  await indexReady;
+  const key = buildKey( payload );
+  try {
+    const lock = await reTriggerLockModel.create( {
+      ...key,
+      status: 'processing',
+      triggeredBy: payload.triggeredBy,
+      triggerType: payload.triggerType,
+    } );
+    return { acquired: true, lock };
+  } catch ( error ) {
+    // Anything other than a duplicate-key collision is a real error.
+    if ( error?.code !== 11000 ) {
+      throw error;
+    }
+
+    // A lock already exists for this combo.
+    let existing = await reTriggerLockModel.findOne( key );
+
+    // Reclaim a stale 'processing' lock left behind by a crashed attempt.
+    if (
+      existing &&
+      existing.status === 'processing' &&
+      Date.now() - new Date( existing.updatedAt ).getTime() > STALE_LOCK_MS
+    ) {
+      // Optimistic guard on updatedAt: only one concurrent reclaimer wins.
+      const reclaimed = await reTriggerLockModel.findOneAndUpdate(
+          { _id: existing._id, status: 'processing', updatedAt: existing.updatedAt },
+          {
+            $set: {
+              status: 'processing',
+              triggeredBy: payload.triggeredBy,
+              triggerType: payload.triggerType,
+            },
+          },
+          { new: true },
+      );
+      if ( reclaimed ) {
+        return { acquired: true, lock: reclaimed };
+      }
+      // Lost the race - re-read whatever the winner left.
+      existing = await reTriggerLockModel.findOne( key );
+    }
+
+    return { acquired: false, lock: existing };
+  }
+}
+
+// Mark the lock completed once processing + SQS send succeeded.
+export function completeReTriggerLock( payload ) {
+  return reTriggerLockModel.updateOne(
+      buildKey( payload ),
+      { $set: { status: 'completed' } },
+  );
+}
+
+// Release (delete) the lock on failure so a legitimate retry can re-acquire it.
+export function releaseReTriggerLock( payload ) {
+  return reTriggerLockModel.deleteOne( buildKey( payload ) );
+}