fix(quotafill): improve safeguard budget utilization

[josemarluedke]

Summary

Optimizes the max_records_examined safeguard in quota-fill pagination to utilize the full examination budget efficiently instead of triggering prematurely.

Problem

The current safeguard logic immediately triggers when the next fetch would exceed the budget:

// Before
if state.examinedCount+fetchSize > w.maxRecordsExamined {
    return safeguardMaxRecords  // Triggers immediately
}

Example scenario:

• maxRecordsExamined = 100
• Currently examined: 95 records
• Next fetch needs: 10 records
• Result: Safeguard triggers, wasting 5 records of budget

This prevents quota-fill from returning as many filtered results as possible within the allowed budget.

Solution

Cap the fetch size to the remaining budget while maintaining the N+1 pagination pattern:

// After
maxAllowed := w.maxRecordsExamined - state.examinedCount
if fetchSize > maxAllowed {
    if maxAllowed < 2 {
        // Need at least 2 for N+1 pattern
        return safeguardMaxRecords
    }
    fetchSize = maxAllowed
    batchSize = fetchSize - 1  // Maintains N+1 pattern
}

Same scenario:

• maxRecordsExamined = 100
• Currently examined: 95 records
• Remaining budget: 5 records
• Result: Cap fetch to 5, return up to 4 items, use 5th for hasNextPage

Key Improvements

1. Better resource utilization - Uses full examination budget instead of wasting it
2. More results returned - Returns more filtered items to users within safeguard limits
3. Maintains N+1 pattern - Correctly preserves hasNextPage detection
4. Edge case handling - Triggers safeguard when budget < 2 (insufficient for N+1)

Testing

• ✅ All 19 quota-fill tests pass
• ✅ Maintains existing safeguard behavior when budget is exhausted
• ✅ N+1 pattern preserved for hasNextPage detection

Impact

• No breaking changes - External API unchanged
• Better UX - Users get more results within their safeguard limits
• Efficiency - Maximizes use of examination budget

---

🤖 Generated with Claude Code