Fix credit-based backpressure documentation accuracy in Backpressure Complete Reference

[Copilot]

The credit-based backpressure documentation in docs/wiki/Backpressure-Complete-Reference.md incorrectly conflated Apache Flink's credit-based flow control with token bucket rate limiting, leading to confusion about the actual mechanisms and their purposes.

Problem

The original documentation presented credit-based flow control as a combination of credit checks AND token bucket rate limiting:

// INCORRECT - Mixed credit + token bucket approach
public class CreditControlledRateLimiter
{
    public bool TryProcessMessage(string consumerId, string message)
    {
        // Credit-based admission control (Ramakrishnan & Jain, 1990)
        if (!HasSufficientCredits(consumerId)) return false;
        
        // Combined credit + token bucket control
        if (!_rateLimiter.TryAcquire()) return false;
        
        return true; // Both credit and rate limit checks passed
    }
}

This approach misrepresented how Apache Flink's credit-based flow control actually works and confused developers about the architectural boundaries between FlinkDotnet client applications and Apache Flink's internal mechanisms.

Solution

Updated the documentation to accurately distinguish between two separate mechanisms:

1. Apache Flink's Credit-Based Flow Control: Internal buffer management between TaskManagers

   • Credits represent actual memory buffer slots
   • Replenished when downstream buffers are consumed
   • Operates within Flink's network stack

2. FlinkDotnet's Token Bucket Rate Limiting: Client-side application flow control

   • Tokens represent time-based permits
   • Replenished at fixed time intervals
   • Operates in client applications before messages reach Flink

Key Changes

• Section 8: Completely rewrote credit-based flow control section with accurate Apache Flink buffer management concepts
• Distinction Table: Added comparison table clearly separating credit-based flow control from token bucket rate limiting
• Code Examples: Replaced mixed examples with proper FlinkCreditBasedFlowController showing buffer management vs FlinkDotnetBackpressureController for client rate limiting
• Integration Architecture: Updated diagrams and descriptions to show correct responsibilities (FlinkDotnet handles client-side rate limiting, Apache Flink handles internal buffer flow control)
• Monitoring Metrics: Fixed production monitoring table to reflect actual integration points

The documentation now provides accurate technical guidance while maintaining its educational value for developers implementing backpressure in FlinkDotnet applications.

Fixes #9.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.