gabriel / muse public
docs protocol dev
AI Agent gabriel · 151 days ago · Apr 23, 2026 · Diff

docs(protocol): rewrite musewire-performance.md — Wall 24 resolved, Wall 25 documented

Remove all outdated batching/rotation/sleep content. Document the single-POST architecture and the current failure (Wall 25: H2 RST_STREAM via CF on large push).

Most atomic next test: W25-A0 — push via direct remote to bypass CF.

sha256:f8d865aab9749ea99d9c03b9dcee6e7476b8cb4fe625a91b40708939947fdc24 sha
sha256:12fcb40ef7af6294d6f1839f5556644fe32c34f2d6667ca91bec87ccd2ecc9bf parent
+48 ~2 −107 symbols
sha256:b04ee5daaa72ebd84827b49a793c3d13a920ab3838963443bf29291d8da9dc40 snapshot
+48
symbols added
~2
symbols modified
−107
symbols removed
0
dead code introduced
Semantic Changes 157 symbols
~ docs/protocol/musewire-performance.md .md 48 symbols added, 107 symbols removed, 2 symbols modified
~ code@L1073
~ Why this doc exists
− MuseWire Protocol — Explicit Frame Framing Roadmap section MuseWire Protocol — Explicit Frame Framing Roadmap L1–1602
− Architecture: Explicit Content-Addressed Frame Framing section Architecture: Explicit Content-Addressed Frame Framing L368–417
− Envelope fields section Envelope fields L398–408
− code[python]@L400 variable variable code[python]@L400 L400–407
− Key invariants section Key invariants L408–417
− The fix: one tight envelope around the existing protocol section The fix: one tight envelope around the existing protocol L378–383
− The problem we are solving (Wall 5) section The problem we are solving (Wall 5) L370–378
− Wire format section Wire format L383–398
− code@L385 variable variable code@L385 L385–388
− table@L389 section table@L389 L389–397
− Current open question section Current open question L1588–1602
− code[bash]@L1595 variable variable code[bash]@L1595 L1595–1599
− Current test status section Current test status L594–617
− code@L596 variable variable code@L596 L596–612
− Done criteria section Done criteria L1562–1588
− Implementation phases section Implementation phases L417–594
− Phase 1 — Client writer ✅ DONE section Phase 1 — Client writer ✅ DONE L419–427
− Phase 10 — Final verify 🔴 BLOCKED (Wall 9) section Phase 10 — Final verify 🔴 BLOCKED (Wall 9) L499–505
− Phase 11 — Legacy cleanup + Wall 9 fix ✅ DONE (client side) section Phase 11 — Legacy cleanup + Wall 9 fix ✅ DONE (client side) L505–515
− Phase 12 — Wall 10 (broken pipe) 🔴 BLOCKED section Phase 12 — Wall 10 (broken pipe) 🔴 BLOCKED L560–594
− Phase 13 — gRPC-only wire protocol ✅ DONE (image 15aba175-20260423103144) section Phase 13 — gRPC-only wire protocol ✅ DONE (image 15aba175-20260423103144) L515–560
− Phase 2 — Client writer tests ✅ DONE section Phase 2 — Client writer tests ✅ DONE L427–437
− Phase 3 — Client transport ✅ DONE section Phase 3 — Client transport ✅ DONE L437–448
− Phase 4 — Server reader ✅ DONE section Phase 4 — Server reader ✅ DONE L448–459
− Phase 5 — Server reader tests ✅ DONE section Phase 5 — Server reader tests ✅ DONE L459–470
− Phase 6 — Integration tests (T1–T6) ✅ DONE section Phase 6 — Integration tests (T1–T6) ✅ DONE L470–481
− Phase 7 — ASGI route tests (T7–T10) ✅ DONE section Phase 7 — ASGI route tests (T7–T10) ✅ DONE L481–488
− Phase 8 — Commit and push both repos ✅ DONE section Phase 8 — Commit and push both repos ✅ DONE L488–493
− Phase 9 — Deploy and verify ✅ DONE (Wall 8 fixed) section Phase 9 — Deploy and verify ✅ DONE (Wall 8 fixed) L493–499
− Inviolable rules section Inviolable rules L617–638
− Phase 14 — Server-Side Object Streaming (GitHub Architecture Parity) section Phase 14 — Server-Side Object Streaming (GitHub Architecture Parity) L193–368
− Phase 14 — Implementation status section Phase 14 — Implementation status L239–257
− table@L241 section table@L241 L241–254
− Phase 14A — Inline streaming: no presign for objects ≤ 290 KB section Phase 14A — Inline streaming: no presign for objects ≤ 290 KB L257–286
− table@L276 section table@L276 L276–283
− Phase 14B — OC-frame protocol: chunked large objects through the stream section Phase 14B — OC-frame protocol: chunked large objects through the stream L286–343
− code@L292 variable variable code@L292 L292–304
− table@L327 section table@L327 L327–340
− Phase 14C — Verify and clean up section Phase 14C — Verify and clean up L343–368
− table@L347 section table@L347 L347–354
− The fix section The fix L215–239
− The problem section The problem L195–215
− Test Pyramid — The Only Way Forward section Test Pyramid — The Only Way Forward L25–193
− Current status section Current status L170–193
− table@L172 section table@L172 L172–180
− Level 1 — Integration test suite section Level 1 — Integration test suite L107–131
− code@L115 variable variable code@L115 L115–126
− Level 2 — nginx integration test section Level 2 — nginx integration test L131–146
− code[bash]@L135 variable variable code[bash]@L135 L135–141
− Level 3 — Staging direct-to-origin section Level 3 — Staging direct-to-origin L146–158
− code[bash]@L150 variable variable code[bash]@L150 L150–153
− Level 4 — Staging full path section Level 4 — Staging full path L158–170
− code[bash]@L162 variable variable code[bash]@L162 L162–165
− Test cases — same set at every level section Test cases — same set at every level L63–87
− table@L69 section table@L69 L69–81
− Test repo — controlled object count section Test repo — controlled object count L87–107
− code[bash]@L91 variable variable code[bash]@L91 L91–94
− The four layers section The four layers L37–63
− code@L39 variable variable code@L39 L39–58
− Wall log section Wall log L638–1562
− Wall 1 — SSLV3 during R2 presigned PUTs (FIXED) section Wall 1 — SSLV3 during R2 presigned PUTs (FIXED) L645–659
− WriteError: [Errno 32] Broken pipe on streaming POST ✅ ROOT-CAUSED → superseded by Wall 11 section Wall 10 — httpx.WriteError: [Errno 32] Broken pipe on streaming POST ✅ ROOT-CAUSED → superseded by Wall 11 L780–804
− Wall 11 — Server receives 0 bytes on push/stream — Cloudflare not forwarding body ✅ ROOT-CAUSED → superseded by Wall 12 section Wall 11 — Server receives 0 bytes on push/stream — Cloudflare not forwarding body ✅ ROOT-CAUSED → superseded by Wall 12 L804–826
− code@L807 variable variable code@L807 L807–810
− SSLError: SSLV3_ALERT_BAD_RECORD_MAC on main push stream ✅ ROOT-CAUSED → superseded by Wall 13 section Wall 12 — ssl.SSLError: SSLV3_ALERT_BAD_RECORD_MAC on main push stream ✅ ROOT-CAUSED → superseded by Wall 13 L826–845
− code@L829 variable variable code@L829 L829–832
− 1 only); Cloudflare gRPC needs HTTP/2 to origin ✅ FIXED section Wall 13 — Production runs uvicorn (HTTP/1.1 only); Cloudflare gRPC needs HTTP/2 to origin ✅ FIXED L845–885
− code@L851 variable variable code@L851 L851–855
− code@L857 variable variable code@L857 L857–861
− Wall 14 — nginx grpc_pass h2c: request body not delivered to ASGI app ✅ FIXED section Wall 14 — nginx grpc_pass h2c: request body not delivered to ASGI app ✅ FIXED L885–925
− code@L890 variable variable code@L890 L890–894
− code@L909 variable variable code@L909 L909–915
− Wall 15 — _WireResponse not subclassing Response: FastAPI JSON-serialized it instead of calling __call__ ✅ FIXED class section Wall 15 — _WireResponse not subclassing Response: FastAPI JSON-serialized it instead of calling __call__ ✅ FIXED L925–960
− code@L930 variable variable code@L930 L930–935
− Wall 16 — Large C frame (~4MB commits) truncated at ~248KB mid-stream ✅ FIXED section Wall 16 — Large C frame (~4MB commits) truncated at ~248KB mid-stream ✅ FIXED L960–1062
− code@L965 variable variable code@L965 L965–983
− code[python]@L1026 variable variable code[python]@L1026 L1026–1043
− Wall 17 — Empty WriteError on push_stream after all R2 PUTs succeed ✅ DIAGNOSED → superseded by Wall 19 section Wall 17 — Empty WriteError on push_stream after all R2 PUTs succeed ✅ DIAGNOSED → superseded by Wall 19 L1062–1120
− code@L1066 variable variable code@L1066 L1066–1070
− code@L1083 variable variable code@L1083 L1083–1088
− code@L1094 variable variable code@L1094 L1094–1098
− Wall 18 — SSLV3_ALERT_BAD_RECORD_MAC on push stream after R2 PUTs section Wall 18 — SSLV3_ALERT_BAD_RECORD_MAC on push stream after R2 PUTs L1120–1166
− code@L1123 variable variable code@L1123 L1123–1126
− Wall 19 — Stream truncation: mid-batch at frame 116 + between-batch RST_STREAM section Wall 19 — Stream truncation: mid-batch at frame 116 + between-batch RST_STREAM L1166–1240
− code@L1208 variable variable code@L1208 L1208–1214
− Wall 2 — int is not allowed for map key when strict_map_key=True (INVALIDATED) section Wall 2 — int is not allowed for map key when strict_map_key=True (INVALIDATED) L659–670
− Wall 20 — Clean EOF mid-stream after grpc_buffer_size fix ✅ SUPERSEDED by Wall 21 section Wall 20 — Clean EOF mid-stream after grpc_buffer_size fix ✅ SUPERSEDED by Wall 21 L1240–1265
− code@L1243 variable variable code@L1243 L1243–1246
− Wall 21 — SSLV3_ALERT_BAD_RECORD_MAC during response read, post-gRPC refactoring section Wall 21 — SSLV3_ALERT_BAD_RECORD_MAC during response read, post-gRPC refactoring L1265–1349
− code@L1271 variable variable code@L1271 L1271–1276
− code[bash]@L1303 variable variable code[bash]@L1303 L1303–1308
− Wall 22 — H2 RST_STREAM after ~4 batches on shared AsyncClient section Wall 22 — H2 RST_STREAM after ~4 batches on shared AsyncClient L1349–1383
− code@L1353 variable variable code@L1353 L1353–1356
− Wall 23 — SSLV3_ALERT_BAD_RECORD_MAC on 2nd batch of 2nd rotation group section Wall 23 — SSLV3_ALERT_BAD_RECORD_MAC on 2nd batch of 2nd rotation group L1383–1427
− Wall 24 — CF rate-limits sequential gRPC connections from same IP section Wall 24 — CF rate-limits sequential gRPC connections from same IP L1427–1528
− code@L1433 variable variable code@L1433 L1433–1437
− code[bash]@L1497 variable variable code[bash]@L1497 L1497–1502
− table@L1466 section table@L1466 L1466–1471
− Wall 3 — SSLV3 on R2 PUT even with no keep-alive (FIXED) section Wall 3 — SSLV3 on R2 PUT even with no keep-alive (FIXED) L670–688
− Wall 4 — SSLV3 persists with fresh client per PUT (FIXED) section Wall 4 — SSLV3 persists with fresh client per PUT (FIXED) L688–703
− Wall 5 — 2662457625 exceeds max_map_len(1073741824) (FIXED) section Wall 5 — 2662457625 exceeds max_map_len(1073741824) (FIXED) L703–734
− code@L706 variable variable code@L706 L706–709
− Wall 6 — SSLV3 returns on R2 PUT #14 (PENDING RETRY) section Wall 6 — SSLV3 returns on R2 PUT #14 (PENDING RETRY) L734–750
− Wall 7 — T7+ ASGI route tests hang (FIXED) section Wall 7 — T7+ ASGI route tests hang (FIXED) L1539–1562
− Wall 8 — 401 on staging push stream after Content-Type rename (FIXED) section Wall 8 — 401 on staging push stream after Content-Type rename (FIXED) L1528–1539
− Wall 9 — invalid frame magic: b'b5ac' after Wall 8 fix (FIXED) section Wall 9 — invalid frame magic: b'b5ac' after Wall 8 fix (FIXED) L750–780
− code@L753 variable variable code@L753 L753–756
+ MuseWire Protocol — Performance & Correctness Log section MuseWire Protocol — Performance & Correctness Log L1–411
+ Architecture section Architecture L25–67
+ Current wire stack (confirmed) section Current wire stack (confirmed) L27–36
+ code@L29 variable variable code@L29 L29–35
+ Push protocol section Push protocol L36–50
+ code@L40 variable variable code@L40 L40–47
+ What was deleted (Wall 24 root cause fix, sha256:bb01c8ec) section What was deleted (Wall 24 root cause fix, sha256:bb01c8ec) L50–67
+ Current test suite section Current test suite L189–210
+ code@L191 variable variable code@L191 L191–207
+ Done criteria section Done criteria L210–223
+ Inviolable rules section Inviolable rules L173–189
+ Test Pyramid section Test Pyramid L67–102
+ Current level status section Current level status L91–102
+ table@L93 section table@L93 L93–99
+ code@L71 variable variable code@L71 L71–90
+ Test fixture section Test fixture L159–173
+ code[bash]@L161 variable variable code[bash]@L161 L161–168
+ Wall 25 — H2 RST_STREAM on single-POST push to staging section Wall 25 — H2 RST_STREAM on single-POST push to staging L102–159
+ Most atomic testable unit — W25-A0 section Most atomic testable unit — W25-A0 L126–147
+ code[bash]@L130 variable variable code[bash]@L130 L130–133
+ TDD items section TDD items L147–159
+ table@L149 section table@L149 L149–156
+ Wall log (history) section Wall log (history) L223–411
+ Wall 1 — SSLV3 during R2 presigned PUTs ✅ FIXED section Wall 1 — SSLV3 during R2 presigned PUTs ✅ FIXED L225–231
+ WriteError: Broken pipe on streaming POST ✅ FIXED section Wall 10 — httpx.WriteError: Broken pipe on streaming POST ✅ FIXED L287–295
+ Wall 11 — Server receives 0 bytes on push/stream ✅ FIXED section Wall 11 — Server receives 0 bytes on push/stream ✅ FIXED L295–302
+ Wall 12 — SSLV3_ALERT_BAD_RECORD_MAC on main push stream ✅ FIXED section Wall 12 — SSLV3_ALERT_BAD_RECORD_MAC on main push stream ✅ FIXED L302–309
+ Wall 13 — Production runs uvicorn; Cloudflare gRPC needs HTTP/2 to origin ✅ FIXED section Wall 13 — Production runs uvicorn; Cloudflare gRPC needs HTTP/2 to origin ✅ FIXED L309–316
+ Wall 14 — nginx grpc_pass h2c: empty body delivered to ASGI app ✅ FIXED section Wall 14 — nginx grpc_pass h2c: empty body delivered to ASGI app ✅ FIXED L316–323
+ Wall 15 — _WireResponse not subclassing Response: FastAPI JSON-serialized it ✅ FIXED class section Wall 15 — _WireResponse not subclassing Response: FastAPI JSON-serialized it ✅ FIXED L323–331
+ Wall 16 — Large C frame (~4MB commits) truncated at ~248KB mid-stream ✅ FIXED section Wall 16 — Large C frame (~4MB commits) truncated at ~248KB mid-stream ✅ FIXED L331–339
+ Wall 17 — Empty WriteError on push_stream after R2 PUTs ✅ ROOT-CAUSED section Wall 17 — Empty WriteError on push_stream after R2 PUTs ✅ ROOT-CAUSED L339–346
+ Wall 18 — SSLV3_ALERT_BAD_RECORD_MAC at __aenter__ ✅ FIXED section Wall 18 — SSLV3_ALERT_BAD_RECORD_MAC at __aenter__ ✅ FIXED L346–353
+ Wall 19 — Non-deterministic mid-frame gRPC truncation ✅ FIXED section Wall 19 — Non-deterministic mid-frame gRPC truncation ✅ FIXED L353–361
+ Wall 2 — int is not allowed for map key ✅ INVALIDATED section Wall 2 — int is not allowed for map key ✅ INVALIDATED L231–237
+ Wall 20 — Clean EOF mid-stream after grpc_buffer_size fix ✅ SUPERSEDED section Wall 20 — Clean EOF mid-stream after grpc_buffer_size fix ✅ SUPERSEDED L361–368
+ Wall 21 — SSLV3_ALERT_BAD_RECORD_MAC during response read, post-gRPC refactoring ✅ SUPERSEDED section Wall 21 — SSLV3_ALERT_BAD_RECORD_MAC during response read, post-gRPC refactoring ✅ SUPERSEDED L368–376
+ Wall 22 — H2 RST_STREAM after ~4 batches on shared AsyncClient ✅ SUPERSEDED section Wall 22 — H2 RST_STREAM after ~4 batches on shared AsyncClient ✅ SUPERSEDED L376–384
+ Wall 23 — SSLV3_ALERT_BAD_RECORD_MAC on 2nd batch of 2nd rotation group ✅ SUPERSEDED section Wall 23 — SSLV3_ALERT_BAD_RECORD_MAC on 2nd batch of 2nd rotation group ✅ SUPERSEDED L384–392
+ Wall 24 — CF per-IP quota of ~28–32 sequential gRPC POSTs ✅ ROOT CAUSE FIXED section Wall 24 — CF per-IP quota of ~28–32 sequential gRPC POSTs ✅ ROOT CAUSE FIXED L392–411
+ table@L396 section table@L396 L396–402
+ Wall 3 — SSLV3 on R2 PUT even with no keep-alive ✅ FIXED section Wall 3 — SSLV3 on R2 PUT even with no keep-alive ✅ FIXED L237–244
+ Wall 4 — SSLV3 persists with fresh client per PUT ✅ FIXED section Wall 4 — SSLV3 persists with fresh client per PUT ✅ FIXED L244–251
+ Wall 5 — 2662457625 exceeds max_map_len ✅ FIXED section Wall 5 — 2662457625 exceeds max_map_len ✅ FIXED L251–259
+ Wall 6 — SSLV3 returns on R2 PUT #14 ✅ SUPERSEDED (presign deleted) section Wall 6 — SSLV3 returns on R2 PUT #14 ✅ SUPERSEDED (presign deleted) L259–266
+ Wall 7 — T7+ ASGI route tests hang ✅ FIXED section Wall 7 — T7+ ASGI route tests hang ✅ FIXED L266–273
+ Wall 8 — 401 on staging push stream after Content-Type rename ✅ FIXED section Wall 8 — 401 on staging push stream after Content-Type rename ✅ FIXED L273–280
+ Wall 9 — invalid frame magic: b'b5ac' ✅ FIXED section Wall 9 — invalid frame magic: b'b5ac' ✅ FIXED L280–287
← Older Oldest on dev
All commits
Newer → Latest on dev

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:f8d865aab9749ea99d9c03b9dcee6e7476b8cb4fe625a91b40708939947fdc24 --body "your comment"