docs(specs): add the S30 Maven virtual spec

Moaz Khalifarequested to merge
mkhalifa/s30-maven-virtual-spec into main

What

Adds the S30 spec: Maven virtual repositories (kind=1), authored under #284 (closed). This is the last of the three virtual-format specs (npm S31 merged, container S32 in !972 (merged)) and the Maven counterpart of S14.

Two resolution shapes live in it:

  • Single-winner for artifacts, version-level (snapshot) metadata, and checksum sidecars — S13's resolution composed over S10's hosted reads and S14's remote operations, with the same hardening S32 carries: the format check beside the kind check on the data-error arm, the soft-deleted-upstream skip with the fallback bar, 1-based contiguous positions per S17, and per-position records.
  • Cross-upstream merge for package-level maven-metadata.xml, the one document a virtual repository authors itself. Merging is the behavior every established Maven virtual repository ships (Artifactory, Nexus, Google Cloud Artifact Registry, CodeArtifact) and what Maven Resolver does client-side when a project lists several repositories; the monolith's virtual registry does not merge, so this is greenfield. The staged AppSec review (#243) is already scoped for the XML parsing this adds.

Merge decisions (made with the DRI during authoring)

  • Best-effort collection with per-position cache fallback; a partial merge answers 200 and records merged_partial.
  • <versions> unioned position-major; <latest>/<release> reconciled by newest <lastUpdated> (Maven Resolver's own rule — no ComparableVersion port); <lastUpdated> is the max.
  • A hosted upstream contributes its stored client-uploaded document, keeping the virtual and direct views in agreement.
  • No merged-document cache: freshness is the inputs' freshness, and metadata_cache_validity_hours > 0 keeps the merged view unpinnable (the failure mode of gitlab#556138). An input-derived ETag answers warm conditional requests from the database reads alone.
  • Snapshot metadata never merges (no sound cross-upstream semantics for timestamped builds); <plugins>-shaped documents serve single-winner.

Merge-order and review routing

The spec carries six Depends on clauses. Two shape this MR's review rather than a later one:

  • Four internal/virtual seam changes are booked (batched per-kind Lookup, health on the list join, per-position records, and the merge's collection-mode entry point), with acceptance owed from the S13 DRI before this spec merges — maintainer review is routed accordingly, same as !972 (merged).
  • #314's Maven steps and a running repository-delete guard land in the same release as this spec's schema MR (the inversion #314's own dependency graph forces).

The remaining clauses gate implementation MRs, not this one: S14's handlers (nearly complete on main), #688 (Retry-After caller), and the S13 Retry-After ratification for the data-error-veto row.

Housekeeping

  • Spec index updated (S30 row: Planned → Approved).
  • Follow-ups tracked in #943 (merged-metadata cache, ADR-007 amendment, plugin-prefix merge, resolution-phase coalescing, S14 metrics amendment).
  • markdownlint clean, vale zero errors, mermaid diagram parse-checked, all internal and cross-spec anchors verified.

Related to #284 (closed)

Merge request reports