Draft: 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).
This is the unified draft: two independently authored S34 candidates were deeply compared (assertion-based grading against fact-checked PyPI protocol ground truth plus a comparative design review), and this spec merges the stronger base with the best elements of the second draft.
Scope: 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 q-value Accept negotiation and a 406 rule; exact
Content-Typeon every response (uv hard-fails without one); strong ETags; PEP 833's HTML freeze honored; PEP 592yankedrendering (state columns ship now, mutations stay with S17). - PEP 658 metadata files: extracted at publish time behind the canonical registry's decompression guard — wheels strict (
METADATAis mandated), sdists tolerant (PKG-INFOwhen present) — served as<file-url>.metadatawith only the PEP 714core-metadatakeys (the legacy spelling crashes incident-window pip; all three resolvers verifiably read the renamed key). A publish-time coherence check requires the archive-internalName/Versionto match the declared fields. - 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 twine's and Poetry's skip-existing matchers;RETURNING-gated exactly-once release counters under concurrency. - 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; alternatives considered during unification are recorded in Resolutions with reasons.
Supersedes !1006 (closed) (the pre-unification draft on suleimiahmed/s34-pypi-hosted-spec); that MR can be closed in favor of this one.
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. The format::pypi scoped label exists and is applied.
After this merges: /planner for the implementation plan MR, then /implement-step per step.
Follow-ups tracked: PEP 740 attestation support in #363.