docs(plans): the ADR-003 amendment records the upload half only
Why this exists
docs/plans/2026-09-03-upload-session-concurrency-cap.md describes what the
handbook ADR-003 amendment records. That description is stale against the
amendment MR, which merged on 2026-09-22.
The plan says handbook!21192
"records that a default S3 install at the two-replica floor meets neither
stated range". The merged paragraph, synced into
docs/adr/003_system_requirements.md on main by 47f3df0ca, does not
say that:
- it bounds the upload half only: "the upload half is met only where the admitted session count times the per-session rate reaches it";
- it says in the next sentence that "the cap is not a bound on the download half";
- it reports one shortfall: "At least one supported configuration falls short on the upload half";
- it measures that shortfall at the replica floor ("while the deployment sits at its replica floor") but gives the floor no number.
The plan still reads the S3 download result as an ADR-003 deviation, as its
## Spec Reference already did. handbook!21192 does not record that half, so
the ADR-003 gate is satisfied for the upload half only. The download half
needs a second handbook amendment, and Step 12 may not merge before it does.
That second amendment has no MR yet.
The plan also still called handbook!21192 open and said the gate waits on it.
The first two commits here were built on a read of the MR at 47dfee5cd1,
before it merged. The third brings the plan in line with the merged text. The
fourth and fifth add and then revert an HPA rewording that conflicted with
main, so together they change nothing. The sixth, 29a6f2970, keeps the S3
download result as a deviation and adds the second gate, after review on this
MR.
Left alone, the plan an implementer reads would say the handbook records a download deviation that the handbook leaves out.
Sites touched
The claim lives at three places in the plan, and all three are fixed rather than only the one the review anchored to. A fourth site is new:
## Spec Reference, the ADR-003 bullet. The amendment now "records the S3 shortfall on the upload half and leaves the download verdict in this plan". The bullet now says handbook!21192 merged on 2026-09-22, where it called the MR open. It also says the S3 download result stays an ADR-003 deviation, and that## Dependenciesgates Step 12 on a second amendment.## Dependencies, the gate bullet's opening paragraph. It said the amendment's "scope is not narrower than the posture". It now says the scope is narrower, and that the S3 download result still owes a second amendment. It also said the local mirror "cannot carry" the amendment, and now says the mirror "carries it only through that sync".## Dependencies, the same bullet's closing paragraph naming handbook!21192. It now says the MR merged, records the S3 shortfall at the replica floor, and satisfies the gate for the upload half only.## Dependencies, a new bullet for the second amendment. Step 12 may not merge before it. The bullet also names what it cannot reach: Step 11's production MR, !2882 (merged), merged on 2026-09-25, so the S3 download deviation is onmainunamended until the second amendment merges.
git grep for 21192 and two-replica floor over the tree at 29a6f2970
finds neither in any other file.
What does not change
- The plan's own
:144verdicts. Both halves still fail on a default S3 install and both still pass on the GCS default.## Spec Referencealready calls the S3 download result "a deviation to amend on the S3 default", so that paragraph is unchanged. The HPA-range paragraph that !2905 (merged) added onmainsays the S3 download half still misses its judged rate at 20 pods, which agrees, so it needs no change either. - The upload-half wording in
## Spec Referenceand## Dependencies. - The first gate bullet and its owner. The bullet stays, because it records why Steps 11 and 12 waited on handbook!21192.
## Status. This is a prose amendment, and the table has a single writer.
Notes for review
- Docs only, one file. 48 reviewable LOC, 36 added and 12 removed, derived at
29a6f2970against the merge baseb5d9d2b92.markdownlint,valeandlycheepass. - This branch predates !2905 (merged) on
main, and needs no rebase.git merge-tree --write-treeof29a6f2970againstorigin/mainat245541f3breturns a clean tree. - File overlap and merge order. One other open MR touches this file:
!2944.
git merge-tree --write-treeof29a6f2970against its head135a891f6returns a clean tree, so no merge order is required and either may land first. - Known stale surface left alone: !2794 (merged)'s own merged description repeats the old wording in its "Merge gate" section. A merged description records what that MR did rather than being a surface an implementer reads, so it is not rewritten here.
- Sources: the review thread on handbook!21192, and the review threads on this MR, note_3917022742 and note_3917226366.
Related to #1035