playlists: promise the count that holds when nothing compresses

The ceiling is 1200 tracks on a library that repeats and 660 on one that
never does; the message said 1000, which would send a reader back into the
wall at 660. It says 500, measured at both ends.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 19 insertions, 8 deletions

diff --git a/docs/playlists.md b/docs/playlists.md
index 45e36fe..232eae5 100644
--- a/docs/playlists.md
+++ b/docs/playlists.md
@@ -1229,14 +1229,25 @@ reads §15.1 as more than it is.
   `UPLOAD_CHUNK_SIZE` is 48 KB going up while `CHUNK_SIZE` is 1 MB coming down,
   which is the same constraint seen from both ends.
 
-  So `USER_BLOB_BODY_MAX = 1 MB` is a cap the client can never reach. Measured
-  rather than derived: a thousand tracks with varied metadata seal to **53 276
-  bytes**, and each further track costs about 50, so one playlist tops out near
-  **1200 tracks**. (An earlier draft of this paragraph said 225, by reading §4's
-  ~270 bytes a track *raw* as the *sealed* figure. `test_playlist_store.py`
-  measures it now, and fails if a thousand tracks stop fitting.) Reading is
-  unaffected — a node answers with a whole body, and 256 KB is measured coming
-  back.
+  So `USER_BLOB_BODY_MAX = 1 MB` is a cap the client can never reach. How many
+  tracks 62 KB is depends entirely on how much the metadata repeats, because
+  repetition is all deflate has to work with — so it was measured at both ends
+  rather than derived:
+
+  | a library where… | per track | one playlist tops out at |
+  |---|---|---|
+  | artists, albums and folders recur | ~50 B | ~1200 tracks |
+  | nothing repeats at all | ~91 B | ~660 tracks |
+
+  Real libraries sit near the first row — an album contributes a dozen tracks
+  sharing three fields — but the sentence shown to a reader has to hold in the
+  second, so it says **500**. (Two earlier drafts of this paragraph were wrong
+  in both directions: 225, from reading §4's ~270 bytes a track *raw* as the
+  *sealed* figure; then 1200, from a fixture with fourteen words of vocabulary,
+  which measured deflate's opinion of its own regularity. Both numbers are now
+  measured by `test_playlist_store.py`, which fails if either stops holding.)
+  Reading is unaffected — a node answers with a whole body, and 256 KB is
+  measured coming back.
 
   **Taken:** the client caps itself at 62 KB of sealed body, checked after
   sealing because compression makes a track count a poor guide to a blob length.