Draft: docs(plans): add S34 PyPI hosted implementation plan

Suleimi Ahmedrequested to merge
suleimiahmed/s34-pypi-hosted-plan into main

What does this MR do and why?

Adds the implementation plan for S34: PyPI hosted (spec in !1007) plus its plan-index row.

Merge order: this branch stacks on the S34 spec commit; !1007 must merge first, after which this MR's diff reduces to the plan file and index row alone. No step MR opens before this plan MR lands (plan-before-implementation guardrail).

Shape:

  • 22 MR-sized steps with four independent roots (schema, PypiConfig, the lexical validation core, the buffered-update helper) and genuine sibling parallelism across the three endpoint tracks (publish, Simple API pages, downloads + metadata files); the step DAG, mermaid graph, and Status table are lockstep-verified.
  • Research-verified against the codebase, not assumed: routing/root-dispatcher mechanics (including the ServeMux 307-redirect trap on slash-less upload URLs — twine and Poetry hard-fail any redirect, so both route forms register explicitly), the auth-dispatch table row, storage Session/OpenBlob signatures, migration idioms (64 unrolled partitions, NOT VALID/VALIDATE enum widening), the five format-enum allowlist sites, config plumbing with the configuration-reference pairing guardrail, CI wiring obligations (lint:integration-test-wiring, fuzz:pypi, conformance:pypi), and npm-plan LOC actuals driving the step sizing and seam-interrogation notes.
  • AC traceability: all 48 spec acceptance criteria map to steps with no gaps; the four error-case rows without a numbered AC are routed explicitly.
  • Validated by three adversarial review rounds with real implementation probes (each in throwaway worktrees, nothing committed): extraction ReaderAt over ranged OpenBlob, the PEP 440 subset, the multipart walk with incremental field caps, migrations passing the pinned squawk, the auth row landing green against live internal/auth tests, renderer determinism with the resolvers' real Accept headers, publish-committer transaction idioms against jet, and the Step 22 lexical surface (22/22 probe subtests) — plus the mandated pr-review-toolkit:review-pr pass. Every finding was fixed in place; round 3 certified the plan.

External dependencies flagged in-plan: the Snowplow artifact_registry_context iglu schema accepting pypi, and the S01 Content-Length pre-check residual (#89 (closed)) affecting large uploads.

Related to !1007

Merge request reports