docs(design): specify request-minimal object protocol

[forhappy]

Summary

• define a hard-cutover v2 protocol built around one immutable publication capsule and one mutable CAS root
• set exact clean-push budgets: three requests with provider-validated checksums, four with independent readback, and P + 4 / P + 5 for multipart uploads
• distinguish the capsule storage container from the Git packfile format required by clone and fetch
• require every checkpoint to include a self-contained non-thin Git pack plus locator, index, visibility, and reconstruction evidence
• specify end-to-end full clone, incremental fetch/pull, shallow fetch, partial clone, lazy object recovery, checkout, and hydration behavior
• define honest read minima: one root GET for advertisement, two reads for an exact authorized checkpoint clone, 2 + D ahead of checkpoint, and 1 + R for incremental fetch
• enforce a hard delta-depth bound with background checkpointing and foreground checkpoint/backpressure when maintenance falls behind
• specify integrity, authorization, observability, qualification, GC, and hard-cutover requirements
• link the proposal from the current push design

Context

PR #200 reduced the modeled v1 clean tiny-push budget from roughly 60 logical object-store operations to roughly 37 without changing the storage format. This proposal describes the hard-cutover protocol required to reach a three-request production clean path while keeping durability, atomic ref publication, Git wire compatibility, reconstruction, authorization, race handling, and GC safety non-negotiable.

Key decisions

The normal push path is:

1. GET and pin v2/root during advertisement.
2. Upload one checksummed immutable capsule.
3. CAS v2/root to atomically publish all ref edits.

Standalone .pack, .idx, and .rev object-store keys disappear, but Git pack bytes remain authenticated sections inside capsules. Crab continues to emit exactly one standard upload-pack packfile response; it does not rely on packfile-uris or expose raw capsule bodies to Git.

A checkpoint includes a complete self-contained Git pack. Exact fully-authorized clones can stream it directly. Other clones and fetches select authorized objects from the checkpoint and bounded capsule frontier, resolve all required delta bases, and generate one self-contained or negotiation-safe thin response pack.

The design intentionally trades possible redundant bytes for fewer high-latency remote requests. Existing remote content may be omitted only when it is authoritatively reachable from the pinned base root.

Validation

• git diff --check
• npm run build
• npm run check:links — 398 HTML pages and 4307 fragments

Documentation-only change; no runtime behavior changes.