Implement Maven virtual repositories per the S30 spec (#284). Depends on the Maven remote implementation (#286) and the S13 virtual/remote foundation. ## Spec and plan - Spec: [`docs/specs/S30-maven-virtual.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S30-maven-virtual.md) - Plan: [`docs/plans/2026-09-10-s30-maven-virtual.md`](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/plans/2026-09-10-s30-maven-virtual.md) ## Scope Maven virtual (`kind=1`) vertical slice: the three `maven_virtual_*` tables, the fixed-count resolution reads, the resolver's virtual tier, the `kind=1` dispatch arm replacing the interim `501`, single-winner resolution over hosted and remote upstreams, the cross-upstream package-level `maven-metadata.xml` merge, sidecar synthesis by parent shape, the observability family, and the end-to-end harness. The rate-limit refusal is out of this plan: [#1181](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1181) delivers the namespace rate-limit check on all six pull arms, keyed on principal, namespace, and IP, and its acceptance criteria name the Maven virtual arm explicitly. Delivered as **24 implementation steps** across two tracks: the schema chain (Steps 1-3) opens the plan and unblocks #314; the resolution/merge track (Steps 4-20) builds the read path. Execution follows the dependency DAG below — **not numeric order**; each step's blockers are its direct predecessors. Step numbers are stable references for MR titles and review. The step total dropped from 25 to 24 when !3103 removed the Maven-only rate-limit mount (Step 16b): a mount delivered inside S30 would be Maven's alone, and each sibling arm would then need its own. **Out of scope:** S13 owns the format-agnostic foundation (Lookup/Probe/Fetch, teed Fetch + cache-fill pipeline, single-flight, cache freshness/fallback, SSRF-hardened upstream client, health monitoring, collection mode). The rate-limit check on the read path is #1181's. S17 owns virtual-repo REST CRUD + association routes (#314). S31 owns npm virtual; S32 owns container virtual. S08/S09 own real auth. ## Dependency DAG ```mermaid graph TD S1["Step 1: maven_virtual_repositories schema"] S2["Step 2: maven_virtual_repository_upstreams schema"] S3["Step 3: maven_virtual_upstream_rules schema"] S4["Step 4: datastore reads for the upstream list and rules"] S5["Step 5: hosted upstream lookup"] S6["Step 6: remote upstream lookup and prober"] S7["Step 7: Maven coordinate and rule adapter"] S8["Step 8: resolver virtual tier"] S9["Step 9: virtual dispatch slot"] S10a["Step 10a: memo adapters and the health reader"] S10b["Step 10b: the wrong-format data-error mark"] S10c["Step 10c: upstream assembly and the fail-closed gates"] S11a["Step 11a: error mapping"] S11b["Step 11b: resolution facade"] S12["Step 12: streaming metadata merger"] S13["Step 13: collection over positions"] S14["Step 14: merged serve surface"] S15["Step 15: composition root"] S16a["Step 16a: merge memory cap"] S17["Step 17: winner-path artifact and metadata handler"] S18["Step 18: sidecar handler by parent shape"] S19a["Step 19a: winner-path observability"] S19b["Step 19b: merge-path observability"] S20["Step 20: end-to-end harness and e2e catalog"] S1 --> S2 S2 --> S3 S3 --> S4 S1 --> S8 S8 --> S9 S4 --> S10a S5 --> S10a S6 --> S10a S10a --> S10c S7 --> S10c S10b --> S10c S10c --> S11a S11a --> S11b S10c --> S13 S12 --> S13 S11a --> S13 S13 --> S14 S16a --> S14 S19a --> S14 S9 --> S15 S11b --> S15 S15 --> S17 S14 --> S18 S17 --> S18 S17 --> S19a S19a --> S19b S18 --> S19b S17 --> S20 S18 --> S20 ``` Steps 1, 5, 6, 7, 10b, 12, and 16a declare `Depends on: —` and open at plan merge. Steps 12 and 16a stay parallel to the whole resolution track. Step 13 was held by the collection-mode plan's remaining steps (5, 6) and has since merged. #688 lands with or before Step 11a. ## Status | Step | Description | MR | Status | Done | Assignee | Dependencies | |------|-------------|----|--------|------|----------|--------------| | 1 | `maven_virtual_repositories` schema — parent table, 64 partitions, unique index, S20-A FK collateral | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2697 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 2 | `maven_virtual_repository_upstreams` schema — junction table, position column, deferrable constraint, reverse index | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2719 | ~"workflow::complete" | [x] | @jdrpereira | Step 1 | | 3 | `maven_virtual_upstream_rules` schema — per-association rule table with range and length CHECKs | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2758 | ~"workflow::complete" | [x] | @jdrpereira | Step 2 | | 4 | Datastore reads for the upstream list and rules — batched reads, contract sidecar | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2769 | ~"workflow::complete" | [x] | @jdrpereira | Step 3 | | 5 | Hosted upstream lookup — batched authoritative read over hosted Maven tables, Phase 1 adapter | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2702 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 6 | Remote upstream lookup and prober — batched cache reads, Phase 1 adapter, bare-`HEAD` prober | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2703 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 7 | Maven coordinate and rule adapter — target fields, coordinate from parsed path, stored-rule adapter | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2690 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 8 | Resolver virtual tier — `Virtual` field on `Resolution`, `VirtualRepositoryFinder`, wire_maven arity change | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2737 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 1 | | 9 | Virtual dispatch slot — `kind=1` arm of `serveDownload`, FIPS `.md5` short-circuit, write-path `405` pin | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2767 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 8 | | 10a | Memo adapters and the health reader — per-request adapters for fixed statement count | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2808 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 4, 5, 6 | | 10b | The wrong-format data-error mark — Maven-side gate consuming S32's Step 10a declaration | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2848 | ~"workflow::complete" | [x] | @mkhalifa3 | —; external: S32 Step 10a | | 10c | Upstream assembly and the fail-closed gates — ordered position list, kind/format checks, soft-delete drop | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2862 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 10a, 7, 10b | | 11a | Error mapping — resolution error surface to Maven envelope, derived enumeration, coalescing sentinels | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2892 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 10c | | 11b | Resolution facade — assemble, resolve, hand back outcome and position list | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2914 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 11a | | 12 | Streaming metadata merger — pure merge, streaming token pass, deterministic output, escaping | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2691 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 13 | Collection over positions — contributor reads, `PositionOutcome`-to-token map, merge-path aggregate arms | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2901 | ~"workflow::complete" | [x] | @jdrpereira | Steps 10c, 11a, 12; external: collection-mode plan steps 5, 6 | | 14 | Merged serve surface — validator, conditional path, exact framing, merge counters, cap slot | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3045 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 13, 16a, 19a | | 15 | Composition root — process-lifetime wiring, production audit sink, flight-registry seam | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2947 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 9, 11b | | 16a | Merge memory cap — byte-weighted in-flight merge budget under `GOMEMLIMIT` | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2692 | ~"workflow::complete" | [x] | @mkhalifa3 | — | | 17 | Winner-path artifact and metadata handler — resolve, serve by winner kind, cache fallback, ADR-012 usage events | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3002 & https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3003 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 11b, 15 | | 18 | Sidecar handler by parent shape — checksum sidecar and package-level metadata arms mounted | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3081 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 14, 17 | | 19a | Winner-path observability — four metric families, `maven_virtual_resolve` wide event, label budgets | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3014 & https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3015 | ~"workflow::complete" | [x] | @mkhalifa3 | Step 17 | | 19b | Merge-path observability — merge outcome values in wide event, `skipped_soft_deleted` records, catalog rows | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3088 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 19a, 18 | | 20 | End-to-end harness and e2e catalog — hermetic harness, coalescing test, e2e scenario catalog | https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/3087 | ~"workflow::complete" | [x] | @mkhalifa3 | Steps 17, 18 | Removed: Step 16b (S05 rate-limit wiring) — dropped by !3103. The Maven-only mount is replaced by #1181's shared check across all six pull arms; #149 owns the S05 Phase 2 primitive. No step on this plan waits for the S05 amendment. ## Cross-workstream dependencies (critical path) - **S13 (virtual/remote foundation)** — the resolution algorithm, health monitoring, and collection mode. Collection-mode steps 1–4 have all merged. Step 5 ([#1248](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1248)) has an open MR ([!2754](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2754)). Step 6 ([#1249](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1249)) is open, gated on the S13 DRI ratifying `position_wait_timeout`. Steps 5 and 6 gate S30's Step 13. - **S14 (Maven remote, #286)** — fully merged. `RemoteOperations`, the `RemoteCacheStore` seams, `BuildRemoteRequestBuilder`, the bare-`HEAD` health probe, sidecar synthesis, and the `maven_remote_proxy` wide-event emitter are consumable as-is. - **S10 (Maven hosted)** — merged. S30 reuses `internal/format/maven/`'s path parser, coordinate grammar, Content-Type mapping, digest support, error envelope, and resolver/dispatcher. - **S32 (container virtual)** — S32's Step 10a declares the wrong-format exclusion reason (constructor, `Reason` classification, `loadAndFilter` arm, audit const) and is a **merge-order prerequisite** for this plan's Step 10b, which consumes it without redeclaring. - **S05 (distributed state) / #1181 / #149** — the rate-limit refusal (429, `too_many_requests`, `Retry-After: 5`, measured per namespace per ADR-004, observe-first rollout) stays S30's spec shape, but its delivery is #1181's: the namespace rate-limit check on all six pull arms, keyed on principal, namespace, and IP. #149 owns the S05 Phase 2 primitive and records that S30's read path is the first workload to need it. No step on this plan waits on either. - **#688** — sets `Retry-After` from `remote.RetryAfterSeconds` on the resolution path. Lands with or before Step 11a. - **#314** — S17 Phase 6's Maven virtual management steps: Step 36 (Maven virtual kind) merged ([!2736](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2736)). Step 41 (Maven upstream associations) is in build, stacked on Step 40 which has an open MR ([!2735](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2735)). - **ADR-007 handbook amendment** — cleared: Steps 1–3 have all merged. - **npm's open Step 14** shares `cmd/artifact-registry/remote_audit_sink.go` with this plan's Step 15. - **npm's open Step 18 and S32's Step 17** share the `resolution_outcome` closed-set union with this plan's Step 19a. ## Related - Spec: #284 - Maven remote: #286 - AppSec review: #991 - Deferred follow-ups: #943 - Rate limit: #1181