docs(specs): add S34 PyPI hosted format spec
What does this MR do and why?
Adds S34: PyPI hosted — the master spec for hosted PyPI repositories — plus its spec-index row. Opened with **Status:** Approved per the spec-MR guardrail (the merge is the approval signal).
Scope decided in the authoring interview: hosted (local) repositories only; remote and virtual PyPI are deferred to future slice specs. Client matrix: pip install, twine upload, Poetry and uv (resolve and publish), and hash-checking CI (pip --require-hashes).
Highlights:
- Read surface: Simple Repository API in HTML (1.0) and JSON (1.1) with Accept negotiation; exact
Content-Typeon every response (uv hard-fails without it); strong ETags; PEP 833's HTML freeze honored. - PEP 658 wheel metadata files: extracted at publish time behind the canonical registry's decompression guard (stored/deflated only, 64 MiB cap, ratio 50), served as
<file-url>.metadatawith the PEP 714core-metadatakeys only — the deciding factor for fast Poetry/uv resolution against a private index. - Publish flow: streaming multipart upload through the S06 two-phase session; fail-closed sha256 policy; append-only filename-claims ledger implementing PyPI's never-reuse-a-filename rule race-free; 409 +
already existsduplicate contract verified against the skip-existing matchers of twine (source, 6.2.0) and Poetry (source, main). - Data model:
pypi_*tables as flagged ADR 007 amendments following the partitioning/UUIDv7/composite-key conventions; format enum value allocated as next-free (4 at drafting), confirmed againstmainat implementation time. - Every protocol claim traces to a source fetched during authoring (PyPA specs, PEP status pages, PyPI docs, and pip/twine/Poetry/uv source); observed-only behavior is explicitly marked and unverifiable claims were excluded.
Amendments to raise separately (flagged in-spec): ADR 004 PyPI limits row, ADR 007 PyPI tables section, ADR 009 PyPI client routes — all handbook-repo MRs. A format::pypi scoped label does not exist yet and needs creating; this MR carries the closest existing label set.
After this merges: /planner for the implementation plan MR, then /implement-step per step.
Follow-ups tracked: PEP 740 attestation support in #363.