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.gointernal/format/npm/in_flight_budget.gointernal/format/oci/in_flight_budget.gointernal/lifecycle/in_flight_budget.gointernal/managementapi/in_flight_budget.gointernal/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-duplicationby 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"), anddocs/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").