{
  "schema_version": "1.3.0",
  "slug": "when-does-a-global-token-bucket-let-one-client-starve-the-rest",
  "title": "When does a global token bucket let one client starve the rest?",
  "date_of_record": "2026 November 1",
  "scope": "Applies to rate limiting where a single token bucket or quota is shared across all clients of a service, with no per-client partitioning. Excludes systems with per-client buckets, or with a global cap layered on top of per-client limits.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/when-does-a-global-token-bucket-let-one-client-starve-the-rest.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/when-does-a-global-token-bucket-let-one-client-starve-the-rest.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/when-does-a-global-token-bucket-let-one-client-starve-the-rest.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 815,
    "python_slice_tokens": 118,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "**Predicate.** A global bucket enforces an aggregate rate but not fair allocation. If one client can consume the whole bucket, fairness requires per-client buckets plus a global cap, and the cap must satisfy global_cap >= per_client_limit * active_clients, or the cap reintroduces contention at a lower level. **Failure.** A single client, whether a retry stor...",
    "what_was_observed": "**Signature.** Aggregate throughput at or near the configured limit. One client receives nearly all of it. The error rate for other clients rises while the limiter reports no violations. **Trace.** Global limit 1000 rps. One batch client issues 5000 rps of requests. The bucket admits 1000 rps and rejects 4000. The batch client retries rejected requests, which consumes the remaining admitted capacity on the next inter...",
    "condition_of_validity": "Fair limiting holds only while at least one holds: 1. **Per-client buckets.** Each client has its own bucket, and the global cap is sized to accommodate all active clients at their individual limits. 2. **Weighted fair queueing.** Admitted capacity is allocated by a fairness rule rather than by arrival order. 3. **Concurrency cap per client.** A hard per-cli...",
    "decision_boundary": "- Per-client buckets and cap at or above the sum: fair. - Per-client buckets and cap below the sum: contention returns at the cap, and the fairness rule must decide allocation there. - Global bucket alone: aggregate compliant, allocation arbitrary. One client can starve the rest. - Global bucket plus retries: the starved client's retries consume capacity, wh...",
    "operational_effect": "The defect converts a capacity guarantee into an allocation lottery, and it does so precisely under the condition it was designed to handle. Remediation is per-client partitioning with a deliberate global cap. The trap is to lower the global limit, which reduces the blast radius and leaves the allocation problem entirely intact."
  },
  "matched_failure_symptoms": [
    "HTTP_429_BURST_STARVATION"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "8da62eb2a87bb23b9db9a7d8cc9db403f9d56720d0088a2c6e5d1f79d9d1220b",
    "verified_classes": [
      "FairShareError",
      "FairShareGate"
    ],
    "verified_functions": [
      "dispatch_limiter_mode",
      "verify"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 2,
    "raised_exceptions": [
      "FairShareError"
    ],
    "sample_fail_closed_invariants": [
      "global bucket only: allocation is arrival-order dependent"
    ],
    "stdlib_dependencies": [
      "dataclasses"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}