Severity: 🟡 medium • Category: doc-mismatch
Location: docs/alternatives.md / README.md / docs/usage.md : alternatives.md:14,30; README.md:172; usage.md:46-66
What's wrong
The async path implements single-flight / dogpile / stampede prevention (commit 17969f1, 'Add async single-flight coalescing'). AsyncCachedFunction.call coalesces concurrent misses on the same key so only one coroutine computes the result while the rest await an asyncio.Event. Despite this, every doc that mentions stampede prevention claims warp_cache does NOT have it and actively steers users to other libraries. alternatives.md's feature table row says 'Stampede prevention: No', alternatives.md:30 says 'If you need stampede prevention ... look at cachebox or moka-py', and README.md:172 lists 'Stampede prevention or per-entry TTL - use cachebox or moka-py'. usage.md's async section (47-66) never mentions the coalescing behavior at all. This is a shipped feature documented as absent, misleading users into picking a different library.
Trigger
Read alternatives.md / README before adopting; a user needing async stampede prevention is told warp_cache lacks it and to use cachebox/moka-py, when warp_cache already provides it for async functions.
Suggested fix
Document async single-flight coalescing in usage.md's async section, update alternatives.md's 'Stampede prevention' row to 'Yes (async)' (or note it is async-only since the sync path has no coalescing), and remove/qualify the README/alternatives statements steering users elsewhere for stampede prevention.
Adversarial verification note
Confirmed by reading the actual code and docs. warp_cache/_decorator.py:49-106 implements async single-flight (stampede/dogpile) coalescing: AsyncCachedFunction.call probes the cache (line 81), and on miss builds an inflight key (line 85) and uses a self._inflight dict of asyncio.Event objects (lines 87-106) so that concurrent misses on the same key wait on the leader's event (lines 88-95) while only the leader computes and stores the result (lines 100-106). The class docstring (lines 56-57) explicitly states "Implements single-flight coalescing." Meanwhile every doc claims the feature is absent: docs/alternatives.md:13 has the table row '| Stampede prevention | No |', alternatives.md:30 says 'If you need stampede prevention or per-entry TTL, look at cachebox or moka-py', and README.md:172 says 'Stampede prevention or per-entry TTL - use cachebox or moka-py'. usage.md's async section (lines 46-66) never mentions the coalescing behavior. So a shipped feature is documented as not existing, and users are actively steered to other libraries. The reviewer's evidence and the async-only caveat are accurate: the sync path returns the bare inner CachedFunction (decorator lines 181-186) which has no Python-level coalescing, so the row should read 'Yes (async)' rather than unqualified 'Yes'. I downgrade severity from high to medium because this is purely a documentation accuracy problem (no wrong results, crash, deadlock, or data loss in code); its only impact is misleading library-selection decisions, which is real but doc-only.
Filed from a multi-agent code review (finder → adversarial verification → synthesis). Confirmed real after a skeptic re-read the code.
Severity: 🟡 medium • Category: doc-mismatch
Location:
docs/alternatives.md / README.md / docs/usage.md: alternatives.md:14,30; README.md:172; usage.md:46-66What's wrong
The async path implements single-flight / dogpile / stampede prevention (commit 17969f1, 'Add async single-flight coalescing'). AsyncCachedFunction.call coalesces concurrent misses on the same key so only one coroutine computes the result while the rest await an asyncio.Event. Despite this, every doc that mentions stampede prevention claims warp_cache does NOT have it and actively steers users to other libraries. alternatives.md's feature table row says 'Stampede prevention: No', alternatives.md:30 says 'If you need stampede prevention ... look at cachebox or moka-py', and README.md:172 lists 'Stampede prevention or per-entry TTL - use cachebox or moka-py'. usage.md's async section (47-66) never mentions the coalescing behavior at all. This is a shipped feature documented as absent, misleading users into picking a different library.
Trigger
Read alternatives.md / README before adopting; a user needing async stampede prevention is told warp_cache lacks it and to use cachebox/moka-py, when warp_cache already provides it for async functions.
Suggested fix
Document async single-flight coalescing in usage.md's async section, update alternatives.md's 'Stampede prevention' row to 'Yes (async)' (or note it is async-only since the sync path has no coalescing), and remove/qualify the README/alternatives statements steering users elsewhere for stampede prevention.
Adversarial verification note
Confirmed by reading the actual code and docs. warp_cache/_decorator.py:49-106 implements async single-flight (stampede/dogpile) coalescing: AsyncCachedFunction.call probes the cache (line 81), and on miss builds an inflight key (line 85) and uses a self._inflight dict of asyncio.Event objects (lines 87-106) so that concurrent misses on the same key wait on the leader's event (lines 88-95) while only the leader computes and stores the result (lines 100-106). The class docstring (lines 56-57) explicitly states "Implements single-flight coalescing." Meanwhile every doc claims the feature is absent: docs/alternatives.md:13 has the table row '| Stampede prevention | No |', alternatives.md:30 says 'If you need stampede prevention or per-entry TTL, look at cachebox or moka-py', and README.md:172 says 'Stampede prevention or per-entry TTL - use cachebox or moka-py'. usage.md's async section (lines 46-66) never mentions the coalescing behavior. So a shipped feature is documented as not existing, and users are actively steered to other libraries. The reviewer's evidence and the async-only caveat are accurate: the sync path returns the bare inner CachedFunction (decorator lines 181-186) which has no Python-level coalescing, so the row should read 'Yes (async)' rather than unqualified 'Yes'. I downgrade severity from high to medium because this is purely a documentation accuracy problem (no wrong results, crash, deadlock, or data loss in code); its only impact is misleading library-selection decisions, which is real but doc-only.
Filed from a multi-agent code review (finder → adversarial verification → synthesis). Confirmed real after a skeptic re-read the code.