Pace candidate funnel to send capacity

src/database/candidate-queue-repository.ts

@@ -44,6 +44,7 @@ export interface CandidateEnqueueResult {
   duplicateAuthor: number;
   previouslyProcessed: number;
   previouslyContacted: number;
+  deferredAtCapacity: number;
 }
 
 const ACTIVE_STATUSES: CandidateStatus[] = ['discovered', 'screening', 'ready', 'sending', 'retryable'];
@@ -57,13 +58,19 @@ export class CandidateQueueRepository {
     sourceType: 'image' | 'chat',
     priority: number,
     now: number = Date.now(),
+    maxNewCandidates: number = Number.POSITIVE_INFINITY,
   ): CandidateEnqueueResult {
+    if ((!Number.isInteger(maxNewCandidates) && maxNewCandidates !== Number.POSITIVE_INFINITY)
+      || maxNewCandidates < 0) {
+      throw new Error('Candidate intake capacity must be a non-negative integer');
+    }
     const result: CandidateEnqueueResult = {
       discovered: 0,
       duplicatePost: 0,
       duplicateAuthor: 0,
       previouslyProcessed: 0,
       previouslyContacted: 0,
+      deferredAtCapacity: 0,
     };
     const existingPost = this.db.prepare('SELECT 1 FROM candidate_queue WHERE post_id = ?');
     const processedPost = this.db.prepare('SELECT 1 FROM processed_posts WHERE id = ? LIMIT 1');
@@ -90,7 +97,11 @@ export class CandidateQueueRepository {
     `);
 
     this.db.transaction(() => {
-      for (const post of posts) {
+      for (const [index, post] of posts.entries()) {
+        if (result.discovered >= maxNewCandidates) {
+          result.deferredAtCapacity += posts.length - index;
+          break;
+        }
         if (existingPost.get(post.id)) {
           result.duplicatePost += 1;
           continue;