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_partialwithout 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
GOMEMLIMITthat no black-box scenario can set. Nodocs/userchange: 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_budgetposition 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)
- refactor(virtual): share one merge memory budge... (!3184 - merged) • David Fernandez • 19.5
- feat(npm): charge the merge parse's retained st... (!3185 - merged) • David Fernandez • 19.5
- feat(npm): hold the merge tail at its encoded s... (!3186 - merged) • David Fernandez • 19.5
- feat(npm): admit the virtual merge against the ... (!3187 - merged) • David Fernandez, Dzmitry (Dima) Meshcharakou • 19.6
👈 - feat(npm): hold the merge budget until the stre... (!3188 - merged) • David Fernandez, Dzmitry (Dima) Meshcharakou • 19.6 (must merge right after this MR: it adds the budget hold this part lacks)
Related to #1524 (closed)