Deduplicate splitQuota and the per-package in-flight cap materializers

The branch for #559 derives every detached-write in-flight cap from the resource it draws on. It leaves two kinds of copied code in the consumer packages. This issue tracks both, because both need the same decision: a home and a name for one shared internal package.

1. splitQuota

splitQuota is the largest-remainder allocator. It seats one slot per member, and then it gives the remaining slots out by weight. The function is byte-identical in two places:

  • internal/format/maven/in_flight_budget.go (splitQuota, lines 106-156)
  • internal/format/npm/in_flight_budget.go (splitQuota, lines 143-193)

The doc comment is identical too. Its two callers, the quota-map builders newBufferedUpdateQuotas (internal/format/maven/in_flight_budget.go:90-104) and newCounterEmitQuotas (internal/format/npm/in_flight_budget.go:127-141), differ only in the map key type (string against counterEmitSite).

2. The per-package cap materializer

Six consumer packages each carry their own copy of one block:

  • internal/format/maven/in_flight_budget.go
  • internal/format/npm/in_flight_budget.go
  • internal/format/oci/in_flight_budget.go
  • internal/lifecycle/in_flight_budget.go
  • internal/managementapi/in_flight_budget.go
  • internal/remote/standalone.go

Each copy has an InFlightBudget struct, an ErrInFlightBudgetNotWired sentinel, a SetInFlightBudget setter, and one materializer per cap. A materializer refuses when the setter did not run, and otherwise makes the process-wide semaphore at its first call. The Known gaps row "Hand-rolled in-flight caps, one copy per consumer package" in docs/dev/storage-accounting.md records this copy.

Each call site keeps the choice to detach, bound, spawn and shed. Work item #920 (closed) ruled that on 2026-09-01, so the dispatch code at the call sites is not in scope here. Only the materializer block is in scope.

What it costs

A duplicated algorithm can diverge without a signal. The seat rule, the largest-remainder distribution and the member-order tie-break are kept in two places. The unwired refusal and the first-acquire materialization are kept in six. Each package's tests pin only its own copy. Nothing in CI reports on the copies: the dupl threshold (.golangci.yaml:451-452) is not met, and no copy carries a //nolint:dupl twin marker.

What the dedup needs decided

The splitQuota extraction is mechanical: the function is pure (int, []int) []int and needs no format types. internal/format/ holds only maven, npm and oci, and no existing package owns a shared quota splitter or a shared semaphore materializer. So the dedup needs a new shared internal package, and these decisions:

  • the package name and the exported signatures;
  • whether the two quota-map builders also move behind a generic keyed helper;
  • whether the six materializer blocks move behind one helper in the same change as splitQuota, or in a second change.

A shared helper that exports a function or a type holds no process-wide instance. The #559 body rejects "one process-wide semaphore shared between two packages", and a helper of that kind is a different shape: each package still owns its own semaphore.

References

  • Raised as splitquota-duplication by the hand-back of the branch for #559. The operator chose this follow-up over an extraction inside that unit.
  • The materializer duplication was a Known gaps row that pointed at #559. The branch for #559 points that row and its three related lines at this issue.
  • The nearest merged positions on the choice: docs/dev/architecture.md:21-23 ("resist creating shared packages prematurely — duplication is cheaper than the wrong abstraction"), AGENTS.md:42-43 ("Stay in scope"), and docs/dev/agentic-development.md:124-127 ("Follow-ups: only for a real gap or risk outside the MR's scope that will still matter once the code moves on").
Edited by Pawel Rozlach