feat(npm): admit the virtual merge against the shared budget, part 4/5

Summary

Part 4 of 5 of a stack of merge requests (each targets the previous one; review and merge bottom-up) that bounds the npm virtual metadata merge's memory with a charged parse and a shared merge memory budget, as the Maven virtual merge already does (#1524 (closed)).

No plan file exists for this work: the work item graded as needing a spec amendment first, and the operator chose to ship the S13 (virtual-remote-foundation), S30 (maven-virtual) and S31 (npm-virtual) amendments in this stack instead of a plan MR.

This part admits the npm virtual merge against the shared budget. After collection, each position reserves max(2 x stored size, 64 KiB) in position order, and the merge is cut to the contiguous prefix that fits. Positions past the cut are recorded omitted_budget (distinct from omitted) with no upstream call, the response is merged_partial without a validator and never answers 304, and a cut that drops a hosted contributor, or admits no position, answers 503. npm shares the one process-wide budget with Maven through the wiring from part 1.

This part does not yet hold the reservation for the length of the merge: a read waits until it is free and gives it back before merging, so the budget paces npm merges but does not bound how many run at once. Part 5 (!3188 (merged)) adds the hold, so it must merge right after this MR.

Governing ADRs

ADR 004 (entity-count limits, 20 upstreams per virtual): no conflict found; admission bounds memory, not counts.

Testing

  • Admission tests: the contiguous prefix that fits, zero admitted, a hosted cut vetoes, reservations per document in position order, tokens for the cut positions, one WARN naming them.
  • Serve tests: full prefix merges with an ETag, a partial prefix is merged_partial without a validator, never 304, zero admitted answers 503 without a merge, a cut hosted contributor vetoes with 503.
  • Wiring tests: the npm composition shares the one budget instance with Maven and refuses a composition without a budget.
  • Build, vet and the unit tests of the touched packages pass at this part. Integration-tagged tests were not run locally; CI runs them.
  • No e2e row is added or affected: budget exhaustion needs a controlled GOMEMLIMIT that no black-box scenario can set. No docs/user change: no user page covers npm virtual merge outcomes.

Plan and spec amendments

  • S13 (virtual-remote-foundation): the foundation text now names npm as a consumer of the shared budget.
  • S31 (npm-virtual): the admission paragraph, the omitted_budget position value, the 503 and 404 rows, the hosted-veto bullet (including that an earlier non-fitting remote can veto a fitting hosted position), the no-validator and 304 text, the acceptance criteria for the omitted prefix and no validator, and amended notes 2 and 4; and a Follow-ups entry recording that the npm merge does not hold its reservation yet, with a matching sentence in the admission paragraph, the memory-bound security consideration and the amended resolution note.
  • Observability docs: the new outcome in the npm metrics and the observability reference.

Size

1337 reviewable lines (added plus removed, at c46e590f against main 7e377f64): 291 production, 859 tests, 120 specs, 67 other docs. The admission logic, the cut's response behavior, the wiring and the tests that pin them are one behavior; the spec and observability text describe exactly that cut.

Stacked MRs (review/merge bottom-up)

Related to #1524 (closed)

Edited by Dzmitry (Dima) Meshcharakou

Merge request reports

Loading
Loading