docs: sha256:d4a0381e4c81492e85bfa34d40a5f21458f27b835bd1946c04f73eb1a68a1613 · gabriel/musehub

docs: comprehensive MWP wire protocol accuracy pass

Every section audited against the live server code. Changes:

Frame format - Add OBJECT_CHUNK (OC) frame to frame table - Correct END frame — was described as having no fields; carries n_objects + n_commits for count-verification; document this - COMMIT_PACK: add snapshot_deltas field; was undocumented

OBJECT frame - Fix base field key: was documented as 'base_id', actual wire key is 'base' - Add 'zstd' and 'delta+zstd' encodings — server supports both; only zlib variants were listed

WireCommit table - Add six missing fields: signer_key_id, toolchain_id, prompt_hash, metadata, reviewed_by, test_runs

WireSnapshot / WireSnapshotDelta - Add full WireSnapshotDelta field table (was completely absent) - Clarify that directories is included in snapshot_id hash

Presigned push flow - Add push/confirm as an explicit Step 3 between R2 PUTs and push/stream - Add push/confirm request/response wire shapes - Fix: the doc jumped from R2 PUT directly to push/stream, which would produce 422 'snapshot object(s) not in push bundle or storage' in prod

Integrity & signatures (new section) - Document server-side Ed25519 signature verification (added this session) - Show the provenance payload format v2 so implementers know exactly what gets signed - Distinguish unsigned / signed commit behaviour and require_signed_commits - Add MSign HTTP request auth note

Negotiation - Fix Content-Type note: accepts msgpack or JSON, was listed as JSON-only

Fetch stream - Clarify request uses msgpack body; add depth field documentation - Mention fetch/objects as the alternative for individual object fetches

Endpoints table - Add Rate limit column with actual values from rate_limits.py - Add push/confirm, fetch/objects, /o/{object_id} CDN — all missing - Fix rate limits for repair endpoints (120/min, not unlisted)

Limits table - Split stream-total vs wire-batch limits for commits and objects - Add presigned threshold rows for clarity

+11

symbols added

~13

symbols modified

−4

symbols removed

dead code introduced

Semantic Changes 28 symbols

~ musehub/templates/musehub/pages/docs_muse_wire.html .html 11 symbols added, 4 symbols removed, 13 symbols modified

− h3: Finalise with push/stream section h3: Finalise with push/stream L292–292

− h3: R2 PUT section h3: R2 PUT L279–279

− h3: Request — section h3: Request — L254–254

− h3: Response — section h3: Response — L262–262

+ h2: Integrity signatures section h2: Integrity signatures L532–532

+ h3: Commit signature verification section h3: Commit signature verification L542–542

+ h3: END frame ( ) section h3: END frame ( ) L192–192

+ h3: MSign request authentication section h3: MSign request authentication L579–579

+ h3: Object integrity section h3: Object integrity L534–534

+ h3: Step 1 — section h3: Step 1 — L314–314

+ h3: Step 2 — R2 PUT section h3: Step 2 — R2 PUT L332–332

+ h3: Step 3 — section h3: Step 3 — L345–345

+ h3: Step 4 — (zero O frames) section h3: Step 4 — (zero O frames) L365–365

+ h3: WireSnapshotDelta fields section h3: WireSnapshotDelta fields L247–247

+ section#integrity section section#integrity L531–587

~ aside@12

~ main#main-content

~ nav[Docs navigation]

~ section#encodings

~ section#endpoints

~ section#fetch

~ section#framing

~ section#limits

~ section#negotiate

~ section#overview

~ section#presign

~ section#push

~ section#refs

← Older Oldest on task/wire-docs-overhaul

All commits

Newer → Latest on task/wire-docs-overhaul

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:d4a0381e4c81492e85bfa34d40a5f21458f27b835bd1946c04f73eb1a68a1613 --body "your comment"