Part of #1035: **upload session concurrency cap**. A global cap over the population that holds object-storage staging buffers, enforced in `internal/storage` where the sessions are opened, with a bounded wait that ends in a `503 UNAVAILABLE` rather than an unbounded park. It changes no commit protocol, no path layout, and no session row shape. **References:** [plan](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/plans/2026-09-03-upload-session-concurrency-cap.md) (see "Step 11"). No spec owns this control: [docs/dev/storage.md](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/storage.md) is the present-tense authority for `BlobStore` and `Session`. The plan's research is pinned at `655743520da9fd935d7884db34ad074e6046013c`, so re-derive any count, line, or file list before acting on it. **Type:** `feat` | **Depends on:** Steps 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | **MR title marker:** `(upload-session-concurrency-cap plan: 11/12)` **Staging soak.** The budget fraction is this plan's one untestable judgement, and unit, integration, conformance and the e2e scenario all run against a *configured* cap rather than a derived one, so none of them measures the derivation against production-like load. See the plan's Step 11 staging-soak bullet for what gates enabling the acquire. ## Scope Make the gate a required parameter of the store, acquire ahead of the row work in `NewSession`, return a release closure, and defer it at each of the five call sites. This is where the cap becomes real for every path except the OCI resume. Four of the five sites take one unit inside `NewSession`; the npm rebuild instead takes both of its units in one `Acquire(ctx, 2)` before the first open and hands the resulting reservation to both, so the rebuild is the one site whose acquire is not inside `NewSession` and whose `defer` releases two units. ## Files - `internal/storage/blobstore.go` (Modify): **both halves of the signature change**. `NewSession` gains a `*SessionReservation` parameter and returns a release func alongside the `Session`. The parameter is why the stub, the three narrowed seams and the fakes all change; the return is why the conformance call sites do. Its doc comment states the caller's obligation, that a caller who drops the `defer` leaks a slot for the process's life, and that a nil or zero reservation means "charge me" while a non-nil one the gate did not issue is rejected. - `internal/storage/pg_session.go` (Modify): acquire ahead of the `upload_sessions` INSERT, not between the INSERT and `driver.Writer`. Acquiring after it would strand a session row for the ADR-011 purger on every shed and would park a waiter that has already round-tripped to Postgres. Pair the acquire with a `defer` that releases unless the constructed `Session` takes ownership, so the paths returning no `Session` at all (the upload-id generation failure, the INSERT failure, and the `driver.Writer` failure) do not strand a slot. - `internal/storage/pg_blobstore.go`, `internal/storage/stack.go`, `cmd/artifact-registry/wire_storage.go` (Modify): the gate as a required constructor parameter, and one gate per process. Not an option: `NewBlobStoreStack` calls `NewBlobStore` with no options and the options file documents that the zero value selects production defaults, so an option would leave production one forgotten line from no cap at all. - `internal/storage/export_test.go` (Create): the in-use count and a capacity override for the external `storage_test` package, modelled on `internal/remote/export_test.go`. - `internal/format/npm/publish_stream.go`, `internal/format/npm/packument_cache.go`, `internal/format/maven/upload.go`, `internal/format/oci/upload.go`, `internal/remote/fetch.go` (Modify): `defer release()` immediately after a successful open, one file per `NewSession` site. - `internal/format/npm/packument_cache.go` (Modify, second change): derive `rebuildMaxRendering` from the configured cap as `min(rebuildMaxRendering, max(1, cap / K))`, clamping down and never up, through a single-purpose `SetRebuildRenderingCap(int)`. The `const` and the `rebuildRenderSem` package global sized from it both move onto the cache as constructor state, the `//nolint:gochecknoglobals` goes with them, and the existing `TODO(s27-cache-rebuild)` is retired rather than left pointing at work this step did. The `rendering_cap` field the shed already logs then carries the derived value. - `internal/format/oci/store.go`, `internal/format/npm/publish.go`, `internal/storage/stub/session.go` (Modify): the narrowed `NewSession` declarations and the stub implementation. Widening `storage.BlobStore.NewSession` is not confined to `internal/storage`: three narrowed seams redeclare the method (`oci/store.go`, `oci/upload.go`, `npm/publish.go`) and the stub implements it, and the compiler enumerates them, which is the point of making the gate a required parameter rather than an option. - `internal/storage/testsuites/session_lifecycle.go`, `internal/storage/testsuites/chunked_upload.go`, `internal/storage/testsuites/session_faults.go`, `internal/storage/testsuites/session_expiry.go` (Modify): the shared `BlobStore` conformance suite called `NewSession` **64** times across these four files at the plan's pin. That count is of `.NewSession(`, method calls rather than name matches; bare `NewSession(` returned 68. Re-derive it at the head SHA before starting. - `internal/storage/emit.go` (Modify): the `outcomeForError` arm for the sentinel, which has to sit above that function's `cancelled` arm. - `internal/metrics/cardinality.go` (Modify): the shed's new `outcome` value. At the plan's pin `closedSetValues["outcome"]` held **25** distinct values against a pinned budget of 26, so this value is legal and takes the label to 26 of 26, leaving no headroom for the next one. The comment beside that budget says 24 and is stale. Re-count before relying on it. - `docs/dev/storage.md`, `docs/dev/storage-composition.md` (Modify): the cap, its derivation and floor, the `chunk_size` coupling, the caller's release obligation, why it waits then sheds where `reserveRenderingSlot` waits, the new shed outcome value added to the documented outcome enum (correcting that row's stale `method` label name to `op` while editing it), and what an operator does when the shed counter rises, which is that the levers are `chunk_size` and the cap, because the CPU-only HPA cannot see a gate full of parked I/O-bound goroutines. - `docs/dev/storage-accounting.md` (Modify): a short paragraph placing this cap **outside** the in-flight cap census, **not** a twelfth row in it. The census's membership test is textual, eleven constants selected by `git grep -n "MaxInFlight = 64" -- internal`, and a config field with a derived default does not match it. Its members are also a kind this gate is not: ten bound a detached worker population and the eleventh sheds without spawning, while this gate **parks** a caller already on the request path. Give that reason. Do **not** offer "bounds staging buffers held by request-path callers, where the eleven bound spawned workers and draw on the Postgres pool or Redis", which is false of the census's eleventh member, `inlineBuildMaxInFlight`, and so argues the opposite of what the paragraph needs. One clause the paragraph must add: "draws on heap" is true of the **wait** and not of the **hold**. - `docs/dev/configuration-reference.md` (Modify): the rows Step 1 could not state as-is, because this is the step that makes them true. That raising the cap is the only way to relax the control; the cap as the second lever in the container-remote fill paragraph, which today ends "Lower `chunk_size` to bound that ceiling"; and the three-way coupling between the cap, `chunk_size` and `rebuildMaxRendering`. - `docs/testing/e2e/oci.md`, `docs/testing/e2e/docker.md` (Modify): the concurrent-push-past-the-cap scenario. ## Acceptance An integration test drives concurrent sessions past the cap and asserts the shed outcome and the counter delta, never a wall-clock floor. The gate the store holds is the **same instance** the composition root built, asserted by identity in an untagged test so it also runs under `-race`, following `TestNewDownloadSignals_SharesTheProcessWideCap`. The slot returns on every post-admission return, driven as a table over the enumerated set rather than a representative sample, and read as **five groups, one per call site**: an OCI-only table is the shape that looks exhaustive and is not. A capacity-N gate admits exactly N again after each case. Per site, the gauge reads the **exact** expected count **while** the site holds its session, not only zero after it returns and not merely at least one: `rebuildStreamedKinds` reads **2**, `rebuildDistTagsKind` reads **1**, and the four single-session sites read 1, so an at-least-one assertion passes on a dist-tags session handed a spent reservation. That criterion is the only one that catches a `defer` booked in an opener that hands the session back. The **capacity gauge** is asserted too, reading the derived cap the composition root passed, since nothing else would catch a gauge wired to the wrong value. So is the **hold-duration histogram**, as an observation recorded at release with a duration inside the window the case holds the session for. The leak arm is not assertable from this step and is not claimed to be: a leaked slot never releases, so no observation exists to assert. For the clamp moved in from Step 10: a cap of 2 yields a rendering ceiling of 1 and a cap of 28 leaves it at 4, asserted as those two numbers so the clamp-down-never-up direction is pinned, and the `rendering_cap` log field carries the derived value on a shed. ## Tests `internal/storage/pg_session_integration_test.go` (Modify), `internal/storage/upload_admission_integration_test.go` (Create), `internal/storage/stack_test.go` (Modify) for the identity assertion, `cmd/artifact-registry/wire_storage_test.go` (Modify) for the composition assertion, and `internal/format/oci/upload_test.go` (Modify) for the arms reached through a real gate rather than a fake store. Three more, because the per-site gauge criterion is required per site and three of the five sites have no file in that list: `internal/format/npm/packument_cache_internal_test.go` (Modify), which is the case that drives the two-unit read, `internal/format/maven/upload_test.go` (Modify), and `internal/remote/fetch_test.go` (Modify). ## Forecast ~390 source, ~600 test, ~990 total. Over the 500-LOC ceiling by ~490; the MR description carries the split by file group.